diff options
Diffstat (limited to 'doc/ci/secrets/convert-to-id-tokens.md')
-rw-r--r-- | doc/ci/secrets/convert-to-id-tokens.md | 102 |
1 files changed, 89 insertions, 13 deletions
diff --git a/doc/ci/secrets/convert-to-id-tokens.md b/doc/ci/secrets/convert-to-id-tokens.md index e9f0d0ef5b0..18803d4de72 100644 --- a/doc/ci/secrets/convert-to-id-tokens.md +++ b/doc/ci/secrets/convert-to-id-tokens.md @@ -5,9 +5,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: tutorial --- -# Tutorial: Update HashiCorp Vault configuration to use ID Tokens **(PREMIUM)** +# Tutorial: Update HashiCorp Vault configuration to use ID Tokens **(PREMIUM ALL)** -This tutorial demonstrates how to convert your existing CI/CI secrets configuration to use [ID Tokens](../secrets/id_token_authentication.md). +This tutorial demonstrates how to convert your existing CI/CD secrets configuration to use [ID Tokens](../secrets/id_token_authentication.md). The `CI_JOB_JWT` variables are deprecated, but updating to ID tokens requires some important configuration changes to work with Vault. If you have more than a handful of jobs, converting everything at once is a daunting task. @@ -20,10 +20,15 @@ Jobs that don't use `secrets:vault` can still use `CI_JOB_JWT` tokens. This tutorial will focus on v16 onwards, if you are running a slightly older version you will need to toggle the `Limit JSON Web Token (JWT) access` setting as appropriate. -To update your vault configuration to use ID tokens: +There isn't one standard method to migrate to [ID tokens](../secrets/id_token_authentication.md), so this tutorial includes two variations for how to convert your existing CI/CD secrets. Choose the method that is most appropriate for your use case: -1. [Create a second JWT authentication path in Vault](#create-a-second-jwt-authentication-path-in-vault) -1. [Recreate roles to use the new authentication path](#recreate-roles-to-use-the-new-authentication-path) +1. Update your Vault configuration: + - Method A: Migrate JWT roles to the new Vault auth method + 1. [Create a second JWT authentication path in Vault](#create-a-second-jwt-authentication-path-in-vault) + 1. [Recreate roles to use the new authentication path](#recreate-roles-to-use-the-new-authentication-path) + - Method B: Move `iss` claim to roles for the migration window + 1. [Add `bound_issuers` claim map to each role](#add-bound_issuers-claim-map-to-each-role) + 1. [Remove `bound_issuers` claim from auth method](#remove-bound_issuers-claim-from-auth-method) 1. [Update your CI/CD Jobs](#update-your-cicd-jobs) ## Prerequisites @@ -36,10 +41,17 @@ To follow along, you must have: - A Vault server that you are already using. - CI/CD jobs retrieving secrets from Vault with `CI_JOB_JWT`. -In the examples below, replace `vault.example.com` with the URL of your Vault server, -and `gitlab.example.com` with the URL of your GitLab instance. +In the examples below, replace: -## Create a second JWT authentication path in Vault +- `vault.example.com` with the URL of your Vault server. +- `gitlab.example.com` with the URL of your GitLab instance. +- `jwt` or `jwt_v2` with your auth method names. + +## Method A: Migrate JWT roles to the new Vault auth method + +This method creates a second JWT auth method in parallel to the existing one in use. Afterwards all Vault roles used for the GitLab integration are recreated in this new auth method. + +### Create a second JWT authentication path in Vault As part of the transition from `CI_JOB_JWT` to ID tokens, you must update the `bound_issuer` in Vault to include `https://`: @@ -69,7 +81,7 @@ You can create multiple authentication paths in Vault, which enable you to trans bound_issuer="https://gitlab.example.com" ``` -## Recreate roles to use the new authentication path +### Recreate roles to use the new authentication path Roles are bound to a specific authentication path so you need to add new roles for each job. @@ -113,6 +125,63 @@ Roles are bound to a specific authentication path so you need to add new roles f You only need to update `jwt` to `jwt_v2` in the `vault` command, do not change the `role_type` inside the role. +## Method B: Move `iss` claim to roles for migration window + +This method doesn't require Vault administrators to create a second JWT auth method and recreate all GitLab related roles. + +### Add `bound_issuers` claim map to each role + +Vault doesn't allow multiple `iss` claims on the JWT auth method level, as the [`bound_issuer`](https://developer.hashicorp.com/vault/api-docs/auth/jwt#bound_issuer) +directive on this level only accepts a single value. However, multiple claims can be configured +on the role level by using the [`bound_claims`](https://developer.hashicorp.com/vault/api-docs/auth/jwt#bound_claims) +map configuration directive. + +With this method you can provide Vault with multiple options for the `iss` claim validation. This supports the `https://` prefixed GitLab instance hostname claim that comes with the `id_tokens`, as well as the old non-prefixed claim. + +To add the [`bound_claims`](https://developer.hashicorp.com/vault/api-docs/auth/jwt#bound_claims) configuration to the required roles, run: + +```shell +$ vault write auth/jwt/role/myproject-staging - <<EOF +{ + "role_type": "jwt", + "policies": ["myproject-staging"], + "token_explicit_max_ttl": 60, + "user_claim": "user_email", + "bound_claims": { + "iss": [ + "https://gitlab.example.com", + "gitlab.example.com" + ], + "project_id": "22", + "ref": "master", + "ref_type": "branch" + } +} +EOF +``` + +You do not need to alter any existing role configurations except for the `bound_claims` section +Make sure to add the `iss` configuration as shown above to ensure Vault accepts +the prefixed and non-prefixed `iss` claim for this role. + +You must apply this change to all JWT roles used for the GitLab integration before moving on to the next step. + +You can revert the migration of the `iss` claim validation from the auth method to the roles if desired, +after all projects have been migrated and you no longer need parallel support for `CI_JOB_JWT` and ID tokens. + +### Remove `bound_issuers` claim from auth method + +After all roles have been updated with the `bound_claims.iss` claims, you can remove the auth method level configuration for this validation: + +```shell +$ vault write auth/jwt/config \ + jwks_url="https://gitlab.example.com/-/jwks" \ + bound_issuer="" +``` + +Setting the `bound_issuer` directive to an empty string removes the issuer validation on the auth method level. +However, as we have moved this validation to the role level, this configuration is still secure. + ## Update your CI/CD Jobs Vault has two different [KV Secrets Engines](https://developer.hashicorp.com/vault/docs/secrets/kv) and the version you are using impacts how you define secrets in CI/CD. @@ -124,7 +193,12 @@ Also, if needed you can review the CI/CD documentation for: - [`secrets:`](../yaml/index.md#secrets) - [`id_tokens:`](../yaml/index.md#id_tokens) -The following examples show how to obtain the staging database password written to the `password` field in `secret/myproject/staging/db` +The following examples show how to obtain the staging database password written to the `password` field in `secret/myproject/staging/db`. + +The value for the `VAULT_AUTH_PATH` variable depends on the migration method you used: + +- Method A (Migrate JWT roles to the new Vault auth method): Use `jwt_v2`. +- Method B (Move `iss` claim to roles for migration window): Use `jwt`. ### KV Secrets Engine v1 @@ -134,7 +208,7 @@ The [`secrets:vault`](../yaml/index.md#secretsvault) keyword defaults to v2 of t job: variables: VAULT_SERVER_URL: https://vault.example.com - VAULT_AUTH_PATH: jwt_v2 + VAULT_AUTH_PATH: jwt_v2 # or "jwt" if you used method B VAULT_AUTH_ROLE: myproject-staging id_tokens: VAULT_ID_TOKEN: @@ -165,7 +239,7 @@ Long format: job: variables: VAULT_SERVER_URL: https://vault.example.com - VAULT_AUTH_PATH: jwt_v2 + VAULT_AUTH_PATH: jwt_v2 # or "jwt" if you used method B VAULT_AUTH_ROLE: myproject-staging id_tokens: VAULT_ID_TOKEN: @@ -189,7 +263,7 @@ You can also use a short format: job: variables: VAULT_SERVER_URL: https://vault.example.com - VAULT_AUTH_PATH: jwt_v2 + VAULT_AUTH_PATH: jwt_v2 # or "jwt" if you used method B VAULT_AUTH_ROLE: myproject-staging id_tokens: VAULT_ID_TOKEN: @@ -201,3 +275,5 @@ job: ``` After you commit the updated CI/CD configuration, your jobs will be fetching secrets with ID Tokens, congratulations! + +If you have migrated all projects to fetch secrets with ID Tokens and used method B for the migration, it is now possible to move the `iss` claim validation back to the auth method configuration if you desire. |