Add latest changes from gitlab-org/gitlab@master

1 files changed, 88 insertions, 12 deletions

diff --git a/doc/ci/secrets/convert-to-id-tokens.md b/doc/ci/secrets/convert-to-id-tokens.md
index e9f0d0ef5b0..6690113273c 100644
--- a/doc/ci/secrets/convert-to-id-tokens.md
+++ b/doc/ci/secrets/convert-to-id-tokens.md
@@ -7,7 +7,7 @@ type: tutorial
 
 # Tutorial: Update HashiCorp Vault configuration to use ID Tokens **(PREMIUM)**
 
-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.