diff options
Diffstat (limited to 'doc/ci/examples/authenticating-with-hashicorp-vault/index.md')
-rw-r--r-- | doc/ci/examples/authenticating-with-hashicorp-vault/index.md | 37 |
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. |