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
|
---
stage: Configure
group: Configure
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
---
# Vault Authentication with GitLab OpenID Connect **(FREE)**
[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.
The following content explains how Vault users can authenticate themselves through
GitLab by using our OpenID authentication feature.
## Prerequisites
1. [Install Vault](https://developer.hashicorp.com/vault/docs/install).
1. Run Vault.
## 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. On the left sidebar, select **Applications**.
1. Fill out the application **Name** and [**Redirect URI**](https://developer.hashicorp.com/vault/docs/auth/jwt#redirect-uris).
1. Select the **OpenID** scope.
1. Select **Save application**.
1. Copy the **Client ID** and **Client Secret**, or keep the page open for reference.
## Enable OpenID Connect on Vault
OpenID Connect (OIDC) is not enabled in Vault by default.
To enable the OIDC authentication provider in Vault, open a terminal session
and run the following command:
```shell
vault auth enable oidc
```
You should see the following output in the terminal:
```plaintext
Success! Enabled oidc auth method at: oidc/
```
## Write the OIDC configuration
To give Vault the application ID and secret generated by GitLab and allow
Vault to authenticate through GitLab, run the following command in the terminal:
```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"
```
Replace `<your_application_id>` and `<your_secret>` with the application ID
and secret generated for your app.
You should see the following output in the terminal:
```shell
Success! Data written to: auth/oidc/config
```
## Write the OIDC role configuration
You must tell Vault the [**Redirect URIs**](https://developer.hashicorp.com/vault/docs/auth/jwt#redirect-uris)
and scopes given to GitLab when you created the application.
Run the following command in the terminal:
```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
```
Replace:
- `<your_vault_instance_redirect_uris>` with redirect URIs that match where your
Vault instance is running.
- `<your_application_id>` with the application ID generated for your app.
The `oidc_scopes` field must include `openid`.
This configuration is saved under the name of the role you are creating. In this
example, we are creating a `demo` role.
WARNING:
If you're using a public GitLab instance, such as GitLab.com, you must specify
the `bound_claims` to allow access only to members of your group or project.
Otherwise, anyone with a public account can access your Vault instance.
## Sign in to Vault
1. Go to your Vault UI. For 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 selected, open the dropdown list and select it.
1. Select **Sign in With GitLab**, which opens a modal window:
1. To allow Vault to sign in through GitLab, select **Authorize**. This redirects you back to your Vault UI as an authenticated user.
## Sign in using the Vault CLI (optional)
You can also sign into Vault using the [Vault CLI](https://developer.hashicorp.com/vault/docs/commands).
1. To sign in with the role configuration you created in the previous example,
run the following command in your terminal:
```shell
vault login -method=oidc port=8250 role=demo
```
This command sets:
- `role=demo` so Vault knows which configuration we'd like to sign in with.
- `-method=oidc` to set Vault to use the `OIDC` sign-in method.
- `port=8250` to set the port that GitLab should redirect to. This port
number must match the port given to GitLab when listing
[Redirect URIs](https://developer.hashicorp.com/vault/docs/auth/jwt#redirect-uris).
After running this command, you should see a link in the terminal.
1. Open this link in a web browser:
You should see in the terminal:
```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.
```
|
