1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
|
---
stage: Verify
group: Pipeline Security
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
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).
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.
From GitLab 15.9 to 15.11, [enable the automatic ID token authentication](../secrets/id_token_authentication.md#enable-automatic-id-token-authentication-deprecated)
setting to enable ID Tokens and disable `CI_JOB_JWT` tokens.
In GitLab 16.0 and later you can use ID tokens without any settings changes.
Jobs that use `secrets:vault` automatically do not have `CI_JOB_JWT` tokens available,
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:
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 CI/CD Jobs](#update-your-cicd-jobs)
## Prerequisites
This tutorial assumes you are familiar with GitLab CI/CD and Vault.
To follow along, you must have:
- An instance running GitLab 15.9 or later, or be on GitLab.com.
- 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.
## 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://`:
```shell
$ vault write auth/jwt/config \
jwks_url="https://gitlab.example.com/-/jwks" \
bound_issuer="https://gitlab.example.com"
```
After you make this change, jobs that use `CI_JOB_JWT` start to fail.
You can create multiple authentication paths in Vault, which enable you to transition to IT Tokens on a project by job basis without disruption.
1. Configure a new authentication path with the name `jwt_v2`, run:
```shell
vault auth enable -path jwt_v2 jwt
```
You can choose a different name, but the rest of these examples assume you used `jwt_v2`, so update the examples as needed.
1. Configure the new authentication path for your instance:
```shell
$ vault write auth/jwt_v2/config \
jwks_url="https://gitlab.example.com/-/jwks" \
bound_issuer="https://gitlab.example.com"
```
## 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.
1. Recreate the role for staging named `myproject-staging`:
```shell
$ vault write auth/jwt_v2/role/myproject-staging - <<EOF
{
"role_type": "jwt",
"policies": ["myproject-staging"],
"token_explicit_max_ttl": 60,
"user_claim": "user_email",
"bound_claims": {
"project_id": "22",
"ref": "master",
"ref_type": "branch"
}
}
EOF
```
1. Recreate the role for production named `myproject-production`:
```shell
$ vault write auth/jwt_v2/role/myproject-production - <<EOF
{
"role_type": "jwt",
"policies": ["myproject-production"],
"token_explicit_max_ttl": 60,
"user_claim": "user_email",
"bound_claims_type": "glob",
"bound_claims": {
"project_id": "22",
"ref_protected": "true",
"ref_type": "branch",
"ref": "auto-deploy-*"
}
}
EOF
```
You only need to update `jwt` to `jwt_v2` in the `vault` command, do not change the `role_type` inside the role.
## 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.
Check the [Which Version is my Vault KV Mount?](https://support.hashicorp.com/hc/en-us/articles/4404288741139-Which-Version-is-my-Vault-KV-Mount-) article on HashiCorp's support portal to check your Vault server.
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`
### KV Secrets Engine v1
The [`secrets:vault`](../yaml/index.md#secretsvault) keyword defaults to v2 of the KV Mount, so you need to explicitly configure the job to use the v1 engine:
```yaml
job:
variables:
VAULT_SERVER_URL: https://vault.example.com
VAULT_AUTH_PATH: jwt_v2
VAULT_AUTH_ROLE: myproject-staging
id_tokens:
VAULT_ID_TOKEN:
aud: https://gitlab.example.com
secrets:
PASSWORD:
vault:
engine:
name: kv-v1
path: secret
field: password
path: myproject/staging/db
file: false
```
Both `VAULT_SERVER_URL` and `VAULT_AUTH_PATH` can be [defined as project or group CI/CD variables](../../ci/variables/index.md#define-a-cicd-variable-in-the-ui),
if preferred.
We use [`secrets:file:false`](../../ci/yaml/index.md#secretsfile) because ID tokens place secrets in a file by default, but we need it to work as a regular variable to match the old behavior.
### KV Secrets Engine v2
There are two formats you can use for the v2 engine.
Long format:
```yaml
job:
variables:
VAULT_SERVER_URL: https://vault.example.com
VAULT_AUTH_PATH: jwt_v2
VAULT_AUTH_ROLE: myproject-staging
id_tokens:
VAULT_ID_TOKEN:
aud: https://gitlab.example.com
secrets:
PASSWORD:
vault:
engine:
name: kv-v2
path: secret
field: password
path: myproject/staging/db
file: false
```
This is the same as the example for the v1 engine but `secrets:vault:engine:name:` is set to `kv-v2` to match the engine.
You can also use a short format:
```yaml
job:
variables:
VAULT_SERVER_URL: https://vault.example.com
VAULT_AUTH_PATH: jwt_v2
VAULT_AUTH_ROLE: myproject-staging
id_tokens:
VAULT_ID_TOKEN:
aud: https://gitlab.example.com
secrets:
PASSWORD:
vault: myproject/staging/db/password@secret
file: false
```
After you commit the updated CI/CD configuration, your jobs will be fetching secrets with ID Tokens, congratulations!
|
