Add latest changes from gitlab-org/gitlab@master

1 files changed, 62 insertions, 0 deletions

diff --git a/doc/ci/secrets/id_token_authentication.md b/doc/ci/secrets/id_token_authentication.md
index ab1cb66e1a9..f622bc2a7b1 100644
--- a/doc/ci/secrets/id_token_authentication.md
+++ b/doc/ci/secrets/id_token_authentication.md
@@ -33,6 +33,68 @@ In this example, the two tokens have different `aud` claims. Third party service
 that do not have an `aud` claim matching their bound audience. Use this functionality to reduce the number of
 services with which a token can authenticate. This reduces the severity of having a token compromised.
 
+### Token payload
+
+The following fields are included in each ID token:
+
+| 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. |
+| `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`. |
+| `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:
+
+```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",
+  "ref_type": "branch",
+  "ref_protected": "true",
+  "environment": "production",
+  "environment_protected": "true"
+}
+```
+
+The ID token is encoded by using RS256 and signed with a dedicated private key. The expiry time for the token is set to
+the job's timeout if specified, or 5 minutes if no timeout is specified.
+
 ## Manual ID Token authentication
 
 You can use ID tokens for OIDC authentication with a third party service. For example: