From f362f1ea1c813e80f30099d56af2be2f78ff8567 Mon Sep 17 00:00:00 2001 From: Allison Browne Date: Tue, 24 Jan 2023 16:20:37 -0500 Subject: [PATCH 1/7] Add documentation for inbound scope --- doc/ci/jobs/ci_job_token.md | 72 +++++++++++++++++++++++++++++-------- 1 file changed, 57 insertions(+), 15 deletions(-) diff --git a/doc/ci/jobs/ci_job_token.md b/doc/ci/jobs/ci_job_token.md index 4ae4456c56c333..4feec40a89de0a 100644 --- a/doc/ci/jobs/ci_job_token.md +++ b/doc/ci/jobs/ci_job_token.md @@ -61,26 +61,71 @@ your [runners](../runners/index.md) to be secure. Avoid: If you have an insecure GitLab Runner configuration, you increase the risk that someone tries to steal tokens from other jobs. -## Limit GitLab CI/CD job token access +## Configure CI/CD 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. -> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/332272) in GitLab 14.4. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/332272) in GitLab 14.6. - -You can limit the access scope of a project's CI/CD job token to increase the +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. + If a job token is leaked it could potentially be used to access data that is private to the job token's user. By limiting the job token access scope, private data cannot be accessed unless projects are explicitly authorized. -Control the job token access scope with an allowlist of other projects authorized -to be accessed by authenticating with the current project's job token. By default -the token scope only allows access to the same project where the token comes from. +There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559) to improve +the access control with more strategic control of the access permissions. + +### Allow access to your project with a CI_JOB_TOKEN + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328553) in GitLab 14.9. [Deployed behind the `:inbound_ci_scoped_job_token` feature flag](../../user/feature_flags.md), disabled by default. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/332272) in GitLab 14.9. + +Control your projects job token scope by creating an `inbound` allowlist of projects which can +access your project via their `CI_JOB_TOKEN`. + +By default the allowlist includes your current project. +Other projects can be added and removed by maintainers with access to both projects. + +The setting that turns this feature on will be enabled by +default for all new projects starting in 15.9. It is recommended that project +maintainers or owners enable this setting at all times, and configure the allowlist +for cross-project access if needed. + +#### Example + +For example, with the `inbound` setting is enabled on 'current project' `A`, we add project `B` to the +`inbound` allowlist. Jobs in the pipeline for 'allowed project' `B` can now access project `A` +via the API. + +### Configure the inbound 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**. +1. Expand **Token Access**. +1. Toggle **Allow access to this project with a CI_JOB_TOKEN** to enabled. +1. Optional. Beneath **Allow CI job tokens from the following projects to access this project** + add projects to the `inbound` job token scope allowlist. The user adding a + project must have at least the Maintainer role in the current project and + at least the Guest role in the allowed project. + +### Limit what your projects job token can 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. +> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/332272) in GitLab 14.4. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/332272) in GitLab 14.6. + +Control your projects job token scope by creating an `outbound` allowlist of projects which +can be accessed by your project's job token. + +By default the allowlist includes your current project. Other projects can be added and removed by maintainers with access to both projects. -This setting is disabled by default for all new projects. It is recommended that project maintainers or owners enable this -setting at all times, and configure the allowlist for cross-project access if needed. +With the setting disabled all projects are considered in the 'allowlist' and the token is +bound only by the users permissions. + +The setting that turns this feature on is disabled by default for all new projects and will be removed in 16.0. +It is recommended that project maintainers or owners enable the `inbound` access control instead + +#### Example 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 @@ -88,7 +133,7 @@ to make an API request to a private project `B`, then `B` must be added to the 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. -### Configure the job token scope limit +### Configure the outbound 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**. @@ -97,9 +142,6 @@ The job token scope is only for controlling access to private projects. 1. Optional. Add existing projects to the token's access scope. The user adding a project must have the Maintainer role in both projects. -There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559) to improve -the feature with more strategic control of the access permissions. - ## Download an artifact from a different pipeline **(PREMIUM)** > `CI_JOB_TOKEN` for artifacts download with the API was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2346) in GitLab 9.5. -- GitLab From 730cdc832fd40ba7e89d29b4659ba794eb1bce7e Mon Sep 17 00:00:00 2001 From: Allison Browne Date: Thu, 2 Feb 2023 16:31:49 -0500 Subject: [PATCH 2/7] Apply technical writer suggestions --- doc/ci/jobs/ci_job_token.md | 35 +++++++++++++++++------------------ 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/doc/ci/jobs/ci_job_token.md b/doc/ci/jobs/ci_job_token.md index 4feec40a89de0a..fe6d43fca6e220 100644 --- a/doc/ci/jobs/ci_job_token.md +++ b/doc/ci/jobs/ci_job_token.md @@ -67,7 +67,7 @@ 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. -If a job token is leaked it could potentially be used to access data that is private +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 be accessed unless projects are explicitly authorized. @@ -76,25 +76,24 @@ the access control with more strategic control of the access permissions. ### Allow access to your project with a CI_JOB_TOKEN -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/328553) in GitLab 14.9. [Deployed behind the `:inbound_ci_scoped_job_token` feature flag](../../user/feature_flags.md), disabled by default. -> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/332272) in GitLab 14.9. +> [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. -Control your projects job token scope by creating an `inbound` allowlist of projects which can -access your project via their `CI_JOB_TOKEN`. +Control your project's job token scope by creating an `inbound` allowlist of projects which can +access your project through its `CI_JOB_TOKEN`. By default the allowlist includes your current project. Other projects can be added and removed by maintainers with access to both projects. -The setting that turns this feature on will be enabled by -default for all new projects starting in 15.9. It is recommended that project -maintainers or owners enable this setting at all times, and configure the allowlist -for cross-project access if needed. +The setting that turns this feature on is enabled by +default for all new projects. We recommend that project maintainers +or owners keep this setting enabled at all times, +and configure the allowlist if cross-project access is needed. #### Example -For example, with the `inbound` setting is enabled on 'current project' `A`, we add project `B` to the +For example, if the `inbound` setting is enabled on 'current project' `A`, you add project `B` to the `inbound` allowlist. Jobs in the pipeline for 'allowed project' `B` can now access project `A` -via the API. +through the API. ### Configure the inbound job token scope allowlist @@ -102,28 +101,28 @@ via the API. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Token Access**. 1. Toggle **Allow access to this project with a CI_JOB_TOKEN** to enabled. -1. Optional. Beneath **Allow CI job tokens from the following projects to access this project** +1. Optional. Under **Allow CI job tokens from the following projects to access this project**, add projects to the `inbound` job token scope allowlist. The user adding a project must have at least the Maintainer role in the current project and at least the Guest role in the allowed project. -### Limit what your projects job token can access +### Limit what your project's job token can 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. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/332272) in GitLab 14.4. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/332272) in GitLab 14.6. -Control your projects job token scope by creating an `outbound` allowlist of projects which +Control your project's job token scope by creating an `outbound` allowlist of projects which can be accessed by your project's job token. -By default the allowlist includes your current project. +By default, the allowlist includes your current project. Other projects can be added and removed by maintainers with access to both projects. -With the setting disabled all projects are considered in the 'allowlist' and the token is -bound only by the users permissions. +With the setting disabled, all projects are considered in the 'allowlist' and the token is +bound only by the user's permissions. The setting that turns this feature on is disabled by default for all new projects and will be removed in 16.0. -It is recommended that project maintainers or owners enable the `inbound` access control instead +Project maintainers or owners should enable the `inbound` access control instead. #### Example -- GitLab From 6999bdea4b877f02595c6b4e1b6ad92063d1618d Mon Sep 17 00:00:00 2001 From: Marcel Amirault Date: Tue, 7 Feb 2023 18:06:36 +0000 Subject: [PATCH 3/7] Apply technical writer suggestions - Move examples to the top - Follow formatting suggestions --- doc/ci/jobs/ci_job_token.md | 81 ++++++++++++++++++++++++------------- 1 file changed, 53 insertions(+), 28 deletions(-) diff --git a/doc/ci/jobs/ci_job_token.md b/doc/ci/jobs/ci_job_token.md index fe6d43fca6e220..9210f2f34346ea 100644 --- a/doc/ci/jobs/ci_job_token.md +++ b/doc/ci/jobs/ci_job_token.md @@ -71,60 +71,85 @@ 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 be accessed unless projects are explicitly authorized. -There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559) to improve -the access control with more strategic control of the access permissions. +There is a proposal to add more strategic control of the access permissions, +see [epic 3559](https://gitlab.com/groups/gitlab-org/-/epics/3559). -### Allow access to your project with a CI_JOB_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. -Control your project's job token scope by creating an `inbound` allowlist of projects which can +Control your project's job token scope by creating an **inbound** allowlist of projects which can access your project through its `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`. + By default the allowlist includes your current project. -Other projects can be added and removed by maintainers with access to both projects. -The setting that turns this feature on is enabled by -default for all new projects. We recommend that project maintainers -or owners keep this setting enabled at all times, -and configure the allowlist if cross-project access is needed. +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 + +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, +but you should enable it again as soon as possible. -#### Example +Prerequisite: -For example, if the `inbound` setting is enabled on 'current project' `A`, you add project `B` to the -`inbound` allowlist. Jobs in the pipeline for 'allowed project' `B` can now access project `A` -through the API. +- You must have at least the Maintainer role for the project. -### Configure the inbound job token scope allowlist +To disable the inbound 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**. 1. Expand **Token Access**. -1. Toggle **Allow access to this project with a CI_JOB_TOKEN** to enabled. -1. Optional. Under **Allow CI job tokens from the following projects to access this project**, - add projects to the `inbound` job token scope allowlist. The user adding a - project must have at least the Maintainer role in the current project and - at least the Guest role in the allowed project. +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 add projects to the inbound allowlist for a project. Projects added to the allowlist +can make API calls from running pipelines by using the CI/CD job token. + +Prerequisite: + +- You must have at least the Maintainer role in the current project and at least + the Guest role in the allowed project. -### Limit what your project's job token can access +To add a project: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Token Access**. +1. Verify **Allow access to this project with a CI_JOB_TOKEN** is enabled. +1. Under **Allow CI job tokens from the following projects to access this project**, + add projects to the allowlist. + +### 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. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/332272) in GitLab 14.4. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/332272) in GitLab 14.6. -Control your project's job token scope by creating an `outbound` allowlist of projects which +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. + +Control your project's job token scope by creating an **outbound** allowlist of projects which can be accessed by your project's job token. By default, the allowlist includes your current project. Other projects can be added and removed by maintainers with access to both projects. -With the setting disabled, all projects are considered in the 'allowlist' and the token is -bound only by the user's permissions. - -The setting that turns this feature on is disabled by default for all new projects and will be removed in 16.0. -Project maintainers or owners should enable the `inbound` access control instead. - -#### Example +With the setting disabled, all projects are considered in the allowlist and the job token is +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 -- GitLab From 4b86837440115d9c3d650c2530b170e57644aebf Mon Sep 17 00:00:00 2001 From: Allison Browne Date: Tue, 7 Feb 2023 18:42:43 -0500 Subject: [PATCH 4/7] Fix anchor links --- doc/ci/jobs/ci_job_token.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/ci/jobs/ci_job_token.md b/doc/ci/jobs/ci_job_token.md index 9210f2f34346ea..648ba78643ffcb 100644 --- a/doc/ci/jobs/ci_job_token.md +++ b/doc/ci/jobs/ci_job_token.md @@ -223,10 +223,10 @@ 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: -- When the [CI/CD job token limit](#limit-gitlab-cicd-job-token-access) is enabled, +- When the [CI/CD job token scopes](#configure-gitlab-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 target project must be [allowlisted for the job token scope limit](#configure-the-job-token-scope-limit). + - 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 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. -- GitLab From 1ea90774877520f0eb0dc440d119eaa355038a71 Mon Sep 17 00:00:00 2001 From: Allison Browne Date: Wed, 8 Feb 2023 14:10:56 -0500 Subject: [PATCH 5/7] Add limit documentation --- doc/ci/jobs/ci_job_token.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/ci/jobs/ci_job_token.md b/doc/ci/jobs/ci_job_token.md index 648ba78643ffcb..98187e2b90e6f9 100644 --- a/doc/ci/jobs/ci_job_token.md +++ b/doc/ci/jobs/ci_job_token.md @@ -122,6 +122,7 @@ Prerequisite: - You must have at least the Maintainer role in the current project and at least the Guest role in the allowed project. +- You must not have more than 100 projects added to the allowlist. To add a project: -- GitLab From 1b2f6ff12e7f5dba09854d40139939e4e2263420 Mon Sep 17 00:00:00 2001 From: Allison Browne Date: Wed, 8 Feb 2023 14:33:19 -0500 Subject: [PATCH 6/7] Fix broken anchor --- doc/ci/jobs/ci_job_token.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/ci/jobs/ci_job_token.md b/doc/ci/jobs/ci_job_token.md index 98187e2b90e6f9..f29b6d7cee5ab3 100644 --- a/doc/ci/jobs/ci_job_token.md +++ b/doc/ci/jobs/ci_job_token.md @@ -224,7 +224,7 @@ 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: -- When the [CI/CD job token scopes](#configure-gitlab-cicd-job-token-access) are enabled, +- 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. -- GitLab From 7f6a6d469496c52beb1318367a658c5388f6d20f Mon Sep 17 00:00:00 2001 From: Marcel Amirault Date: Thu, 9 Feb 2023 01:42:56 +0000 Subject: [PATCH 7/7] Apply 1 suggestion(s) to 1 file(s) --- doc/ci/jobs/ci_job_token.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/ci/jobs/ci_job_token.md b/doc/ci/jobs/ci_job_token.md index f29b6d7cee5ab3..d9cfbdf124ebfb 100644 --- a/doc/ci/jobs/ci_job_token.md +++ b/doc/ci/jobs/ci_job_token.md @@ -160,6 +160,12 @@ The job token scope is only for controlling access to private projects. ### Configure the outbound 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: + 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Token Access**. -- GitLab