diff options
Diffstat (limited to 'doc/ci/jobs/ci_job_token.md')
| -rw-r--r-- | doc/ci/jobs/ci_job_token.md | 65 |
1 files changed, 42 insertions, 23 deletions
diff --git a/doc/ci/jobs/ci_job_token.md b/doc/ci/jobs/ci_job_token.md index d9cfbdf124e..9cbf45a16e7 100644 --- a/doc/ci/jobs/ci_job_token.md +++ b/doc/ci/jobs/ci_job_token.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +group: Pipeline Security info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -12,7 +12,7 @@ When a pipeline job is about to run, GitLab generates a unique token and injects You can use a GitLab CI/CD job token to authenticate with specific API endpoints: - Packages: - - [Package Registry](../../user/packages/package_registry/index.md#use-gitlab-cicd-to-build-packages). + - [Package Registry](../../user/packages/package_registry/index.md#to-build-packages). - [Packages API](../../api/packages.md) (project-level). - [Container Registry](../../user/packages/container_registry/build_and_push_images.md#use-gitlab-cicd) (the `$CI_REGISTRY_PASSWORD` is `$CI_JOB_TOKEN`). @@ -30,7 +30,7 @@ job to run. A user can cause a job to run by taking action like pushing a commit triggering a manual job, or being the owner of a scheduled pipeline. Therefore, this user must be assigned to [a role that has the required privileges](../../user/permissions.md#gitlab-cicd-permissions). -The token is valid only while the pipeline job runs. After the job finishes, you can't +The token is valid only while the pipeline job runs. After the job finishes, you cannot use the token anymore. A job token can access a project's resources without any configuration, but it might @@ -65,7 +65,9 @@ tries to steal tokens from other jobs. You can control what projects a CI/CD job token can access to increase the job token's security. A job token might give extra permissions that aren't necessary -to access specific private resources. +to access specific private resources. The job token scope only controls access +to private projects. If an accessed project is public or internal, token scoping does +not apply. If a job token is leaked, it could potentially be used to access private data to the job token's user. By limiting the job token access scope, private data cannot @@ -74,38 +76,44 @@ be accessed unless projects are explicitly authorized. There is a proposal to add more strategic control of the access permissions, see [epic 3559](https://gitlab.com/groups/gitlab-org/-/epics/3559). +NOTE: +Because `CI_REGISTRY_TOKEN` uses `CI_JOB_TOKEN` to authenticate, the access configuration +also applies to `CI_REGISTRY_TOKEN`. + ### Allow access to your project with a job token -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346298/) in GitLab 15.9. [Deployed behind the `:inbound_ci_scoped_job_token` feature flag](../../user/feature_flags.md), enabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346298/) in GitLab 15.9. [Deployed behind the `:inbound_ci_scoped_job_token` feature flag](../../user/feature_flags.md), enabled by default. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/346298/) in GitLab 15.10. -Control your project's job token scope by creating an **inbound** allowlist of projects which can -access your project through its `CI_JOB_TOKEN`. +Create an allowlist of projects which can access your project through +their `CI_JOB_TOKEN`. -For example, you can add project `B` to the inbound allowlist for project `A`. Jobs -in the pipeline for "allowed project" `B` can now use the CI/CD job token to authenticate -API calls to access project `A`. +For example, project `A` can add project `B` to the allowlist. CI/CD jobs +in project `B` (the "allowed project") can now use their CI/CD job token to +authenticate API calls to access project `A`. If project `A` is public or internal, +the project can be accessed by project `B` without adding it to the allowlist. -By default the allowlist includes your current project. +By default, the allowlist of any project only includes itself. It is a security risk to disable this feature, so project maintainers or owners should keep this setting enabled at all times. Add projects to the allowlist only when cross-project access is needed. -### Disable the inbound job token scope allowlist +### Disable the job token scope allowlist WARNING: It is a security risk to disable the allowlist. A malicious user could try to compromise a pipeline created in an unauthorized project. If the pipeline was created by one of your maintainers, the job token could be used in an attempt to access your project. -You can disable the inbound job token scope allowlist for testing or a similar reason, +You can disable the job token scope allowlist for testing or a similar reason, but you should enable it again as soon as possible. Prerequisite: - You must have at least the Maintainer role for the project. -To disable the inbound job token scope allowlist: +To disable the job token scope allowlist: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > CI/CD**. @@ -113,9 +121,11 @@ To disable the inbound job token scope allowlist: 1. Toggle **Allow access to this project with a CI_JOB_TOKEN** to disabled. Enabled by default in new projects. -### Add a project to the inbound job token scope allowlist +You can also disable the allowlist [with the API](../../api/graphql/reference/index.md#mutationprojectcicdsettingsupdate). -You can add projects to the inbound allowlist for a project. Projects added to the allowlist +### Add a project to the job token scope allowlist + +You can add projects to the allowlist for a project. Projects added to the allowlist can make API calls from running pipelines by using the CI/CD job token. Prerequisite: @@ -133,6 +143,8 @@ To add a project: 1. Under **Allow CI job tokens from the following projects to access this project**, add projects to the allowlist. +You can also add a target project to the allowlist [with the API](../../api/graphql/reference/index.md#mutationcijobtokenscopeaddproject). + ### Limit your project's job token access > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328553) in GitLab 14.1. [Deployed behind the `:ci_scoped_job_token` feature flag](../../user/feature_flags.md), disabled by default. @@ -141,9 +153,9 @@ To add a project: NOTE: This feature is disabled by default for all new projects and is [scheduled for removal](https://gitlab.com/gitlab-org/gitlab/-/issues/383084) -in GitLab 16.0. Project maintainers or owners should enable the **inbound** access control instead. +in GitLab 17.0. Project maintainers or owners should enable the access control instead. -Control your project's job token scope by creating an **outbound** allowlist of projects which +Control your project's job token scope by creating an allowlist of projects which can be accessed by your project's job token. By default, the allowlist includes your current project. @@ -155,16 +167,16 @@ limited only by the user's access permissions. For example, when the setting is enabled, jobs in a pipeline in project `A` have a `CI_JOB_TOKEN` scope limited to project `A`. If the job needs to use the token to make an API request to a private project `B`, then `B` must be added to the allowlist for `A`. -If project `B` is public or internal, it's not required to be added to the allowlist. -The job token scope is only for controlling access to private projects. +If project `B` is public or internal, you do not need to add +`B` to the allowlist to grant access. -### Configure the outbound job token scope +### Configure the job token scope Prerequisite: - You must not have more than 100 projects added to the token's scope. -To configure the outbound job token scope: +To configure the job token scope: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > CI/CD**. @@ -230,10 +242,17 @@ CI job token failures are usually shown as responses like `404 Not Found` or sim While troubleshooting CI/CD job token authentication issues, be aware that: +- A [GraphQL example mutation](../../api/graphql/getting_started.md#update-project-settings) + is available to toggle the scope settings per project. +- [This comment](https://gitlab.com/gitlab-org/gitlab/-/issues/351740#note_1335673157) + demonstrates how to use graphQL with Bash and cURL to: + - Enable the inbound token access scope. + - Give access to project B from project A, or add B to A's allowlist. + - To remove project access. - When the [CI/CD job token scopes](#configure-cicd-job-token-access) are enabled, and the job token is being used to access a different project: - The user that executes the job must be a member of the project that is being accessed. - The user must have the [permissions](../../user/permissions.md) to perform the action. - - The accessed project must have the project attempting to access it [added to the inbound allowlist](#add-a-project-to-the-inbound-job-token-scope-allowlist). + - The accessed project must have the project attempting to access it [added to the allowlist](#add-a-project-to-the-job-token-scope-allowlist). - The CI job token becomes invalid if the job is no longer running, has been erased, or if the project is in the process of being deleted. |