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
|
---
stage: Release
group: Release
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
type: reference, howto
---
# Vault Authentication with GitLab OpenID Connect
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/22323) in GitLab 9.0
[Vault](https://www.vaultproject.io/) is a secrets management application offered by HashiCorp.
It allows you to store and manage sensitive information such as secret environment variables, encryption keys, and authentication tokens.
Vault offers Identity-based Access, which means Vault users can authenticate through several of their preferred cloud providers.
This document explains how Vault users can authenticate themselves through GitLab by utilizing our OpenID authentication feature.
The following assumes you already have Vault installed and running.
1. **Get the OpenID Connect client ID and secret from GitLab:**
First you must create a GitLab application to obtain an application ID and secret for authenticating into Vault.
To do this, sign in to GitLab and follow these steps:
1. In the top-right corner, select your avatar.
1. Select **Edit profile**.
1. In the left sidebar, select **Applications**.
1. Fill out the application **Name** and [**Redirect URI**](https://www.vaultproject.io/docs/auth/jwt#redirect-uris).
1. Select the **OpenID** scope.
1. Select **Save application**.
1. Copy client ID and secret, or keep the page open for reference.
1. **Enable OIDC auth on Vault:**
OpenID Connect is not enabled in Vault by default. This needs to be enabled in the terminal.
Open a terminal session and run the following command to enable the OpenID Connect authentication provider in Vault:
```shell
vault auth enable oidc
```
You should see the following output in the terminal:
```plaintext
Success! Enabled oidc auth method at: oidc/
```
1. **Write the OIDC configuration:**
Next, Vault needs to be given the application ID and secret generated by GitLab.
In the terminal session, run the following command to give Vault access to the GitLab application you've just created with an OpenID scope. This allows Vault to authenticate through GitLab.
Replace `your_application_id` and `your_secret` in the example below with the application ID and secret generated for your app:
```shell
$ vault write auth/oidc/config \
oidc_discovery_url="https://gitlab.com" \
oidc_client_id="your_application_id" \
oidc_client_secret="your_secret" \
default_role="demo" \
bound_issuer="localhost"
```
You should see the following output in the terminal:
```shell
Success! Data written to: auth/oidc/config
```
1. **Write the OIDC Role Configuration:**
Now that Vault has a GitLab application ID and secret, it needs to know the [**Redirect URIs**](https://www.vaultproject.io/docs/auth/jwt#redirect-uris) and scopes given to GitLab during the application creation process. The redirect URIs need to match where your Vault instance is running. The `oidc_scopes` field needs to include the `openid`. Similarly to the previous step, replace `your_application_id` with the generated application ID from GitLab:
This configuration is saved under the name of the role you are creating. In this case, we are creating a `demo` role. Later, we show how you can access this role through the Vault CLI.
WARNING:
If you're using a public GitLab instance (GitLab.com or any other instance publicly
accessible), it's paramount to specify the `bound_claims` to allow access only to
members of your group/project. Otherwise, anyone with a public account can access
your Vault instance.
```shell
vault write auth/oidc/role/demo -<<EOF
{
"user_claim": "sub",
"allowed_redirect_uris": "your_vault_instance_redirect_uris",
"bound_audiences": "your_application_id",
"oidc_scopes": "openid",
"role_type": "oidc",
"policies": "demo",
"ttl": "1h",
"bound_claims": { "groups": ["yourGroup/yourSubgrup"] }
}
EOF
```
1. **Sign in to Vault:**
1. Go to your Vault UI (example: [http://127.0.0.1:8200/ui/vault/auth?with=oidc](http://127.0.0.1:8200/ui/vault/auth?with=oidc)).
1. If the `OIDC` method is not currently selected, open the dropdown and select it.
1. Click the **Sign in With GitLab** button, which opens a modal window:
1. Click **Authorize** on the modal to allow Vault to sign in through GitLab. This redirects you back to your Vault UI as a signed-in user.
1. **Sign in using the Vault CLI** (optional):
Vault also allows you to sign in via their CLI.
After writing the same configurations from above, you can run the command below in your terminal to sign in with the role configuration created in step 4 above:
```shell
vault login -method=oidc port=8250 role=demo
```
Here's a short explanation of what this command does:
1. In the **Write the OIDC Role Configuration** (step 4), we created a role called
`demo`. We set `role=demo` so Vault knows which configuration we'd like to
sign in with.
1. To set Vault to use the `OIDC` sign-in method, we set `-method=oidc`.
1. To set the port that GitLab should redirect to, we set `port=8250` or
another port number that matches the port given to GitLab when listing
[Redirect URIs](https://www.vaultproject.io/docs/auth/jwt#redirect-uris).
After running the command, it presents a link in the terminal.
Click the link in the terminal and a browser tab opens that confirms you're signed into Vault via OIDC:
The terminal outputs:
```plaintext
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.
```
|
