This is a Controlled Document
Inline with GitLab's regulatory obligations, changes to controlled documents must be approved or merged by a code owner. All contributions are welcome and encouraged.
The Token Management Standard defines approved GitLab token usage, settings, and distribution for the purposes of providing authentication and authorization within the various systems and subsystems used by the GitLab product.
For some elements of this standard, there will be technology, techniques, settings, and variations thereof being referenced that are currently not implemented. In those cases, this standard is meant to provide specific guidance for future development and implementation.
The Token Management Standard allows for a more consistent approach to token usage within GitLab, easier adaptation to industry standards and compliance frameworks (such as FedRAMP), and an overall more secure product and working environment. In addition, most of the standards are based off recommendations from NIST (National Institute of Standards and Technology) as many of the compliance frameworks are based on NIST standards, and NIST consistently makes solid recommendations that are adopted by many organizations globally.
The Token Management Standard applies to all GitLab team members, contractors, consultants, vendors, and other service providers that handle, manage, store or transmit GitLab data.
This is required for coding best practices as well as account and authenticator management involving tokens for the GitLab product itself. Basically, if it touches GitLab or GitLab customer data, the standard applies.
| Role | Responsibility |
|---|---|
| GitLab Team Members | Responsible for adhering to the requirements outlined in this standard |
| Security Management and Cryptographic Officer | Responsible for approving changes and exceptions to this standard |
| DRI for Token(s) | Reviews and approval authority for all Owner, and Maintainer role assignments |
| Management | Review and approval authority for all Group and Project memberships |
| Group Owners, Group Maintainers, Project Owners, Project Maintainers | Group and Project account management, and token management duties including but not limited to creating, revoking, and monitoring the use and distribution of Group, Project, Deploy, and Runner Token objects |
GitLab team members, contractors, consultants, vendors and other service providers are required to regularly review and understand this Token Management Standard, and how to request, approve, distribute, use and protect GitLab tokens to maintain security. This document is subject to be updated at any time, the aforementioned people are responsible for tracking changes.
GitLab customers are responsible for managing their own accounts and tokens, should consider these standards as highly recommended, and adopt them according to their own internal requirements. GitLab handles Customer Data internally according to our non-disclosure obligations written in our Mutual Non-Disclosure Agreement, and we use the controls identified in this standard.
**.*)Roles associated with tokens:
| Role | Privilege state |
|---|---|
Site Administrator ** |
Privileged |
Developers *** |
Both privileged and non-privileged, depending on specific roles |
| Group Owner | Privileged |
| Group Maintainer | Privileged |
| Project Owner | Privileged |
| Project Maintainer | Privileged |
| Group Developer | Non-privileged |
| Group Reporter | Non-privileged |
| Group Guest | Non-privileged |
| Project Developer | Non-privileged |
| Project Reporter | Non-privileged |
| Project Guest | Non-privileged |
All assignments of the Group Owner, Group Maintainer, Project Owner, Project Maintainer roles must be limited, documented, and approved by the Site Administrator (AC-2(i), AC-5, IA-4 *).
All Impersonation tokens must be approved by the Site Administrator (AC-5 *).
All Group and Project membership must be approved by the respective Group and Project Owners (AC-5 *). All existing Group and Project memberships will be reviewed semiannually, and membership that is no longer appropriate will be removed (AC-2(j), AC-2(7) *).
All registered Runners will be reviewed semiannually, and any unnecessary instances will be removed.
Group and Project Maintainer and Owner roles assume and share the responsibilities of "Account Managers" for their respective Groups or Projects including but not limited to token approval, creation, revocation, usage monitoring (AC-2(b)(e)(f)(g) *). These roles are identified here as they can create tokens at the Group and Project level. This is essentially account creation as the creation of a token is also the creation of the associated bot account.
All Group, Project, Runner Registration, and Deploy tokens must be approved by an Account Manager. (AC-2(c)(d)(e) *)
To allow for the possibility of small teams and personnel having two roles, but still maintain a level of process integrity, account managers should enlist other account managers for token creation and reporting. An Account Manager may not approve their own token (AC-5 *).
A log or inventory of active tokens will be maintained by Account Managers for each group. (This will be a heavy administrative lift for large teams that issue many tokens.)
Account Managers will review token usage and revoke any unnecessary or unused tokens at least monthly (AC-2(j), AC-2(3) *).
Account Managers will revoke any token reported as compromised by the token holder (AC-2(12) *).
GitLab supervisors/GitLab customers will notify all Group owners of employment status changes that may require adjustment in rights and permissions (AC-2(h) *).
Group and project tokens will be revoked when a member leaves the group or project for termination or reassignment (AC-2(h) *).
Storage of tokens outside the GitLab environment must have suitable protection at a level equal to or greater than the Group or Project the token provides access to (IA-5(6) *).
Sharing and distribution of tokens will be limited, and must include documentation, and identity verification of who the token is being distributed to (IA-5(a) *).
GitLab team members will not distribute tokens to non-team members (AC-21, AC-22 *).
Token names will include the Group/Project name, and the creation date (YYYYMMDD) (IA-2, IA-5(b) *).
Tokens will be created with the minimum role and scope necessary to perform the desired task(s) (AC-6 *).
Tokens will never be created with the Maintainer or Owner role (AC-6 *).
Tokens will be created with the shortest reasonable expiration time to accomplish the desired task, but in all cases shall have expiration date not to exceed: (AC-2(3) *)
The "random" part of a token (excluding prefixes and other additions) will be generated using a FIPS-certified and cryptographically-approved algorithm.
Compromised tokens must be mitigated immediately. As compromised tokens can lead to various dangers such as disclosure of sensitive data, unauthorized access, and even privilege escalation in some cases, any compromise must be taken seriously. At GitLab the standard is for immediate revocation of the token followed by an investigation to assess potential impact. It is understood that immediate revocation of a compromised token may break existing access and automation. This impact is typically much smaller than the risk associated with a valid token being used by a malicious actor. As it is possible to automate some of the detection methods to assist in detecting a compromised token, these automated detection methods should also include the capability to automate the revocation as well.
All methods, procedures, notifications, and automations for mitigating a compromised token need to be fully documented. At GitLab any changes to any processes need to be approved by the Security Department, specifically SIRT. Major changes (e.g. potential impact to production) need to be communicated in advance to all relevant parties.
The lifecycle of a token (creation, attributes, usage, and deletion) must be logged for auditing purposes.
The logging of token activities can be stored "locally" in limited quantities, but backup/offsite storage is recommended.
With logging, the token value itself must remain hidden or masked to prevent token compromise.
Any code developed to use tokens must include documentation which contains the following:
Token use must be logged by the code triggering the token authentication (AC-6(9) *). Log events will include at a minimum:
GitLab team members given possession of tokens will maintain control and protection of those tokens and notify Account Managers if it is believed that a token is corrupted or has been compromised in some way.
Production and development environments require the use of different tokens. Tokens will not be shared between environments.
Exceptions to this policy will be tracked as per the Information Security Policy Exception Management Process and currently, potential exceptions need the permission of Security Assurance.
* The references (e.g. "AC-2(a)") are detailed in NIST SP 800-53 Rev. 5.
** The role of "administrator" or "site administrator" implies the main responsible overseer of the GitLab instance. Within GitLab SaaS this is known as the Owner. In a self-managed instance and Dedicated this is the Admin.
*** Developer implies coding, but any "developers" of projects that require tokens for various automation purposes are considered "developers" in this context.