diff options
Diffstat (limited to 'doc/ci/secrets/id_token_authentication.md')
| -rw-r--r-- | doc/ci/secrets/id_token_authentication.md | 130 |
1 files changed, 76 insertions, 54 deletions
diff --git a/doc/ci/secrets/id_token_authentication.md b/doc/ci/secrets/id_token_authentication.md index f622bc2a7b1..1ff2a6efbcf 100644 --- a/doc/ci/secrets/id_token_authentication.md +++ b/doc/ci/secrets/id_token_authentication.md @@ -1,12 +1,14 @@ --- stage: Verify -group: Pipeline Authoring +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 type: tutorial --- # OpenID Connect (OIDC) Authentication Using ID Tokens **(FREE)** +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356986) in GitLab 15.7. + You can authenticate with third party services using GitLab CI/CD's [ID tokens](../yaml/index.md#id_tokens). @@ -35,60 +37,72 @@ services with which a token can authenticate. This reduces the severity of havin ### Token payload -The following fields are included in each ID token: +The following standard claims are included in each ID token: + +| Field | Description | +|--------------------------------------------------------------------|-------------| +| [`iss`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.1) | Issuer of the token, which is the domain of the GitLab instance ("issuer" claim). | +| [`sub`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.2) | `project_path:{group}/{project}:ref_type:{type}:ref:{branch_name}` ("subject" claim). | +| [`aud`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.3) | Intended audience for the token ("audience" claim). Specified in the [ID tokens](../yaml/index.md#id_tokens) configuration. The domain of the GitLab instance by default. | +| [`exp`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.4) | The expiration time ("expiration time" claim). | +| [`nbf`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.5) | The time after which the token becomes valid ("not before" claim). | +| [`iat`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.6) | The time the JWT was issued ("issued at" claim). | +| [`jti`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.7) | Unique identifier for the token ("JWT ID" claim). | + +The token also includes custom claims provided by GitLab: | Field | When | Description | |-------------------------|------------------------------|-------------| -| [`aud`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.3) | Always | Intended audience for the token ("audience" claim). Configured in GitLab the CI/CD configuration. The domain of the GitLab instance by default. | -| [`exp`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.4) | Always | The expiration time ("expiration time" claim). | -| [`iat`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.6) | Always | The time the JWT was issued ("issued at" claim). | -| [`iss`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.1) | Always | Issuer of the token, which is the domain of the GitLab instance ("issuer" claim). | -| [`jti`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.7) | Always | Unique identifier for the token ("JWT ID" claim). | -| [`nbf`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.5) | Always | The time after which the token becomes valid ("not before" claim). | -| [`sub`](https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1.2) | Always | The job ID ("subject" claim). | -| `deployment_tier` | Job specifies an environment | [Deployment tier](../environments/index.md#deployment-tier-of-environments) of the environment the job specifies. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363590) in GitLab 15.2. | -| `environment_protected` | Job specifies an environment | `true` if specified environment is protected, `false` otherwise. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294440) in GitLab 13.9. | -| `environment` | Job specifies an environment | Environment the job specifies. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294440) in GitLab 13.9. | -| `job_id` | Always | ID of the job. | -| `namespace_id` | Always | Use to scope to group or user level namespace by ID. | -| `namespace_path` | Always | Use to scope to group or user level namespace by path. | +| `namespace_id` | Always | Use this to scope to group or user level namespace by ID. | +| `namespace_path` | Always | Use this to scope to group or user level namespace by path. | +| `project_id` | Always | Use this to scope to project by ID. | +| `project_path` | Always | Use this to scope to project by path. | +| `user_id` | Always | ID of the user executing the job. | +| `user_login` | Always | Username of the user executing the job. | +| `user_email` | Always | Email of the user executing the job. | | `pipeline_id` | Always | ID of the pipeline. | | `pipeline_source` | Always | [Pipeline source](../jobs/job_control.md#common-if-clauses-for-rules). | -| `project_id` | Always | Use to scope to project by ID. | -| `project_path` | Always | Use to scope to project by path. | -| `ref_protected` | Always | `true` if the Git ref is protected, `false` otherwise. | -| `ref_type` | Always | Git ref type, either `branch` or `tag`. | +| `job_id` | Always | ID of the job. | | `ref` | Always | Git ref for the job. | -| `user_email` | Always | Email of the user executing the job. | -| `user_id` | Always | ID of the user executing the job. | -| `user_login` | Always | Username of the user executing the job. | - -Example ID token payload: +| `ref_type` | Always | Git ref type, either `branch` or `tag`. | +| `ref_path` | Always | Fully qualified ref for the job. For example, `refs/heads/main`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/119075) in GitLab 16.0. | +| `ref_protected` | Always | `true` if the Git ref is protected, `false` otherwise. | +| `environment` | Job specifies an environment | Environment this job deploys to ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294440) in GitLab 13.9). | +| `environment_protected` | Job specifies an environment | `true` if deployed environment is protected, `false` otherwise ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294440) in GitLab 13.9). | +| `deployment_tier` | Job specifies an environment | [Deployment tier](../environments/index.md#deployment-tier-of-environments) of the environment the job specifies. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363590) in GitLab 15.2. | +| `runner_id` | Always | ID of the runner executing the job. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/404722) in GitLab 16.0. | +| `runner_environment` | Always | The type of runner used by the job. Can be either `gitlab-hosted` or `self-hosted`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/404722) in GitLab 16.0. | +| `sha` | Always | The commit SHA for the job. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/404722) in GitLab 16.0. | ```json { - "jti": "c82eeb0c-5c6f-4a33-abf5-4c474b92b558", - "aud": "hashicorp.example.com", - "iss": "gitlab.example.com", - "iat": 1585710286, - "nbf": 1585798372, - "exp": 1585713886, - "sub": "job_1212", - "namespace_id": "1", - "namespace_path": "mygroup", - "project_id": "22", - "project_path": "mygroup/myproject", - "user_id": "42", - "user_login": "myuser", - "user_email": "myuser@example.com", - "pipeline_id": "1212", - "pipeline_source": "web", - "job_id": "1212", - "ref": "auto-deploy-2020-04-01", + "namespace_id": "72", + "namespace_path": "my-group", + "project_id": "20", + "project_path": "my-group/my-project", + "user_id": "1", + "user_login": "sample-user", + "user_email": "sample-user@example.com", + "pipeline_id": "574", + "pipeline_source": "push", + "job_id": "302", + "ref": "feature-branch-1", "ref_type": "branch", - "ref_protected": "true", - "environment": "production", - "environment_protected": "true" + "ref_path": "refs/heads/feature-branch-1", + "ref_protected": "false", + "environment": "test-environment2", + "environment_protected": "false", + "deployment_tier": "testing", + "runner_id": 1, + "runner_environment": "self-hosted", + "sha": "714a629c0b401fdce83e847fc9589983fc6f46bc", + "jti": "235b3a54-b797-45c7-ae9a-f72d7bc6ef5b", + "iss": "https://gitlab.example.com", + "iat": 1681395193, + "nbf": 1681395188, + "exp": 1681398793, + "sub": "project_path:my-group/my-project:ref_type:branch:ref:feature-branch-1", + "aud": "https://vault.example.com" } ``` @@ -118,15 +132,6 @@ manual_authentication: You can use ID tokens to automatically fetch secrets from HashiCorp Vault with the [`secrets`](../yaml/index.md#secrets) keyword. -### Enable automatic ID token authentication - -To enable automatic ID token authentication: - -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 **Limit JSON Web Token (JWT) access** to enabled. - ### Configure automatic ID Token authentication If one ID token is defined, the `secrets` keyword automatically uses it to authenticate with Vault. For example: @@ -163,3 +168,20 @@ job_with_secrets: - access-first-db.sh --token $FIRST_DB_PASSWORD - access-second-db.sh --token $SECOND_DB_PASSWORD ``` + +<!--- start_remove The following content will be removed on remove_date: '2023-08-22' --> + +### Enable automatic ID token authentication (deprecated) + +WARNING: +This setting was [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/391886) in GitLab 16.0. +ID token authentication is now always available, and JSON Web Token access is always limited. + +To enable automatic ID token authentication: + +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 **Limit JSON Web Token (JWT) access** to enabled. + +<!--- end_remove --> |