1 files changed, 31 insertions, 6 deletions
diff --git a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md
index 7208caaccae..125ae3650c9 100644
--- a/doc/ci/examples/authenticating-with-hashicorp-vault/index.md
+++ b/doc/ci/examples/authenticating-with-hashicorp-vault/index.md
@@ -90,7 +90,7 @@ The JWT is encoded by using RS256 and signed with a dedicated private key. The e
 
 You can use this JWT and your instance's JWKS endpoint (`https://gitlab.example.com/-/jwks`) to authenticate with a Vault server that is configured to allow the JWT Authentication method for authentication.
 
-When configuring roles in Vault, you can use [bound_claims](https://developer.hashicorp.com/vault/docs/auth/jwt#bound-claims) to match against the JWT's claims and restrict which secrets each CI job has access to.
+When configuring roles in Vault, you can use [bound claims](https://developer.hashicorp.com/vault/docs/auth/jwt#bound-claims) to match against the JWT claims and restrict which secrets each CI/CD job has access to.
 
 To communicate with Vault, you can use either its CLI client or perform API requests (using `curl` or another client).
 
@@ -180,10 +180,35 @@ $ vault write auth/jwt/role/myproject-production - <<EOF
 EOF
 ```
 
-This example uses [bound_claims](https://developer.hashicorp.com/vault/api-docs/auth/jwt#bound_claims) to specify that only a JWT with matching values for the specified claims is allowed to authenticate.
+This example uses [bound claims](https://developer.hashicorp.com/vault/api-docs/auth/jwt#bound_claims) to specify that only a JWT with matching values for the specified claims is allowed to authenticate.
 
 Combined with [protected branches](../../../user/project/protected_branches.md), you can restrict who is able to authenticate and read the secrets.
 
+To use the same policy for a list of projects, use `namespace_id`:
+
+```json
+"bound_claims": {
+  "namespace_id": ["12", "22", "37"]
+}
+```
+
+Any of the claims [included in the JWT](#how-it-works) can be matched against a list of values
+in the bound claims. For example:
+
+```json
+"bound_claims": {
+  "user_login": ["alice", "bob", "mallory"]
+}
+
+"bound_claims": {
+  "ref": ["main", "develop", "test"]
+}
+
+"bound_claims": {
+  "project_id": ["12", "22", "37"]
+}
+```
+
 [`token_explicit_max_ttl`](https://developer.hashicorp.com/vault/api-docs/auth/jwt#token_explicit_max_ttl) specifies that the token issued by Vault, upon successful authentication, has a hard lifetime limit of 60 seconds.
 
 [`user_claim`](https://developer.hashicorp.com/vault/api-docs/auth/jwt#user_claim) specifies the name for the Identity alias created by Vault upon a successful login.
@@ -225,7 +250,7 @@ $ vault write auth/jwt/config \
     bound_issuer="gitlab.example.com"
 ```
 
-[bound_issuer](https://developer.hashicorp.com/vault/api-docs/auth/jwt#bound_issuer) specifies that only a JWT with the issuer (that is, the `iss` claim) set to `gitlab.example.com` can use this method to authenticate, and that the JWKS endpoint (`https://gitlab.example.com/-/jwks`) should be used to validate the token.
+[`bound_issuer`](https://developer.hashicorp.com/vault/api-docs/auth/jwt#bound_issuer) specifies that only a JWT with the issuer (that is, the `iss` claim) set to `gitlab.example.com` can use this method to authenticate, and that the JWKS endpoint (`https://gitlab.example.com/-/jwks`) should be used to validate the token.
 
 For the full list of available configuration options, see Vault's [API documentation](https://developer.hashicorp.com/vault/api-docs/auth/jwt#configure).
 
@@ -256,7 +281,7 @@ NOTE:
 If you're using a Vault instance provided by HashiCorp Cloud Platform,
 you need to export the `VAULT_NAMESPACE` variable. Its default value is `admin`.
 
-![read_secrets staging](img/vault-read-secrets-staging.png)
+![read secrets staging example](img/vault-read-secrets-staging.png)
 
 The following job is able to authenticate using the `myproject-production` role and read secrets under `/secret/myproject/production/`:
 
@@ -279,14 +304,14 @@ read_secrets:
     - echo $PASSWORD
 ```
 
-![read_secrets production](img/vault-read-secrets-production.png)
+![read secrets production example](img/vault-read-secrets-production.png)
 
 ### Limit token access to Vault secrets
 
 You can control `CI_JOB_JWT` access to Vault secrets by using Vault protections
 and GitLab features. For example, restrict the token by:
 
-- Using Vault [bound_claims](https://developer.hashicorp.com/vault/docs/auth/jwt#bound-claims)
+- Using Vault [bound claims](https://developer.hashicorp.com/vault/docs/auth/jwt#bound-claims)
   for specific groups using `group_claim`.
 - Hard coding values for Vault bound claims based on the `user_login` and `user_email`
   of specific users.