diff options
Diffstat (limited to 'doc/ci/cloud_services/index.md')
| -rw-r--r-- | doc/ci/cloud_services/index.md | 52 |
1 files changed, 37 insertions, 15 deletions
diff --git a/doc/ci/cloud_services/index.md b/doc/ci/cloud_services/index.md index b7129d92205..9304e3562d9 100644 --- a/doc/ci/cloud_services/index.md +++ b/doc/ci/cloud_services/index.md @@ -4,19 +4,34 @@ group: Pipeline Authoring 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 --- -# Connect to cloud services +# Connect to cloud services **(FREE)** > - `CI_JOB_JWT` variable for reading secrets from Vault [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207125) in GitLab 12.10. > - `CI_JOB_JWT_V2` variable to support additional OIDC providers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/346737) in GitLab 14.7. +> - [ID tokens](../yaml/index.md) to support any OIDC provider, including HashiCorp Vault, [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/356986) in GitLab 15.7. -GitLab CI/CD supports [OpenID Connect (OIDC)](https://openid.net/connect/faq/) that allows your build and deployment job access to cloud credentials and services. Historically, teams stored secrets in projects or applied permissions on the GitLab Runner instance to build and deploy. To support this, a predefined variable named `CI_JOB_JWT_V2` is included in the CI/CD job allowing you to follow a scalable and least-privilege security approach. +GitLab CI/CD supports [OpenID Connect (OIDC)](https://openid.net/connect/faq/) to +give your build and deployment jobs access to cloud credentials and services. +Historically, teams stored secrets in projects or applied permissions on the GitLab Runner +instance to build and deploy. OIDC capable [ID tokens](../yaml/index.md#id_tokens) are configurable +in the CI/CD job allowing you to follow a scalable and least-privilege security approach. + +In GitLab 15.6 and earlier, you must use `CI_JOB_JWT_V2` instead of an ID token, +but it is not customizable. In GitLab 14.6 an earlier you must use the `CI_JOB_JWT`, which has limited support. ## Requirements - Account on GitLab. - Access to a cloud provider that supports OIDC to configure authorization and create roles. -The original implementation of `CI_JOB_JWT` supports [HashiCorp Vault integration](../examples/authenticating-with-hashicorp-vault/index.md). The updated implementation of `CI_JOB_JWT_V2` supports additional cloud providers with OIDC including AWS, Azure, GCP, and Vault. +ID tokens and `CI_JOB_JWT_V2` support cloud providers with OIDC, including: + +- AWS +- Azure +- GCP +- HashiCorp Vault + +The `CI_JOB_JWT` only supports the [HashiCorp Vault integration](../examples/authenticating-with-hashicorp-vault/index.md). NOTE: Configuring OIDC enables JWT token access to the target environments for all pipelines. @@ -25,10 +40,6 @@ review for the pipeline, focusing on the additional access. You can use the [sof as a starting point, and for more information about supply chain attacks, see [How a DevOps Platform helps protect against supply chain attacks](https://about.gitlab.com/blog/2021/04/28/devops-platform-supply-chain-attacks/). -The `CI_JOB_JWT_V2` variable is available for testing, but the full feature is planned -to be generally available when [issue 360657](https://gitlab.com/gitlab-org/gitlab/-/issues/360657) -is complete. - ## Use cases - Removes the need to store secrets in your GitLab group or project. Temporary credentials can be retrieved from your cloud provider through OIDC. @@ -39,18 +50,18 @@ is complete. ## How it works -Each job has a JSON web token (JWT) provided as a CI/CD [predefined variable](../variables/predefined_variables.md) named `CI_JOB_JWT` or `CI_JOB_JWT_V2`. This JWT can be used to authenticate with the OIDC-supported cloud provider such as AWS, Azure, GCP, or Vault. +Each job can be configured with ID tokens, which are provided as a CI/CD variable. These JWTs can be used to authenticate with the OIDC-supported cloud provider such as AWS, Azure, GCP, or Vault. The following fields are included in the JWT: | Field | When | Description | | ----------------------- | ------ | ----------- | +| `aud` | Always | Specified in the [ID tokens](../yaml/index.md#id_tokens) configuration | | `jti` | Always | Unique identifier for this token | | `iss` | Always | Issuer, the domain of your GitLab instance | | `iat` | Always | Issued at | | `nbf` | Always | Not valid before | | `exp` | Always | Expires at | -| `aud` | Always | Issuer, the domain of your GitLab instance | | `sub` | Always |`project_path:{group}/{project}:ref_type:{type}:ref:{branch_name}` | | `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 | @@ -72,7 +83,7 @@ The following fields are included in the JWT: { "jti": "c82eeb0c-5c6f-4a33-abf5-4c474b92b558", "iss": "https://gitlab.example.com", - "aud": "https://gitlab.example.com", + "aud": "https://vault.example.com", "iat": 1585710286, "nbf": 1585798372, "exp": 1585713886, @@ -102,8 +113,8 @@ sequenceDiagram participant GitLab Note right of Cloud: Create OIDC identity provider Note right of Cloud: Create role with conditionals - Note left of GitLab: CI/CD job with CI_JOB_JWT_V2 - GitLab->>+Cloud: Call cloud API with CI_JOB_JWT_V2 + Note left of GitLab: CI/CD job with ID token + GitLab->>+Cloud: Call cloud API with ID token Note right of Cloud: Decode & verify JWT with public key (https://gitlab/-/jwks) Note right of Cloud: Validate audience defined in OIDC Note right of Cloud: Validate conditional (sub, aud) role @@ -115,14 +126,25 @@ sequenceDiagram 1. Create an OIDC identity provider in the cloud (for example, AWS, Azure, GCP, Vault). 1. Create a conditional role in the cloud service that filters to a group, project, branch, or tag. -1. The CI/CD job includes a predefined variable `CI_JOB_JWT_V2` that is a JWT token. You can use this token for authorization with your cloud API. +1. The CI/CD job includes an ID token which is a JWT token. You can use this token for authorization with your cloud API. 1. The cloud verifies the token, validates the conditional role from the payload, and returns a temporary credential. ## Configure a conditional role with OIDC claims -To configure the trust between GitLab and OIDC, you must create a conditional role in the cloud provider that checks against the JWT token. The condition is validated against the JWT to create a trust specifically against two claims, the audience and subject. +To configure the trust between GitLab and OIDC, you must create a conditional role in the cloud provider that checks against the JWT. +The condition is validated against the JWT to create a trust specifically against two claims, the audience and subject. + +- Audience or `aud`: Configured as part of the ID token: + + ```yaml + job_needing_oidc_auth: + id_tokens: + OIDC_TOKEN: + aud: https://oidc.provider.com + script: + - echo $OIDC_TOKEN + ``` -- Audience or `aud`: The URL of the GitLab instance. This is defined when the identity provider is first configured in your cloud provider. - Subject or `sub`: A concatenation of metadata describing the GitLab CI/CD workflow including the group, project, branch, and tag. The `sub` field is in the following format: - `project_path:{group}/{project}:ref_type:{type}:ref:{branch_name}` |