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
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
|
---
stage: Manage
group: Authentication and Authorization
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: reference
---
# Smartcard authentication **(PREMIUM SELF)**
GitLab supports authentication using smartcards.
## Existing password authentication
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33669) in GitLab 12.6.
By default, existing users can continue to sign in with a username and password when smartcard
authentication is enabled.
To force existing users to use only smartcard authentication,
[disable username and password authentication](../settings/sign_in_restrictions.md#password-authentication-enabled).
## Authentication methods
GitLab supports two authentication methods:
- X.509 certificates with local databases.
- LDAP servers.
### Authentication against a local database with X.509 certificates
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/726) in GitLab 11.6 as an experimental feature.
WARNING:
Smartcard authentication against local databases may change or be removed completely in future
releases.
Smartcards with X.509 certificates can be used to authenticate with GitLab.
To use a smartcard with an X.509 certificate to authenticate against a local
database with GitLab, `CN` and `emailAddress` must be defined in the
certificate. For example:
```plaintext
Certificate:
Data:
Version: 1 (0x0)
Serial Number: 12856475246677808609 (0xb26b601ecdd555e1)
Signature Algorithm: sha256WithRSAEncryption
Issuer: O=Random Corp Ltd, CN=Random Corp
Validity
Not Before: Oct 30 12:00:00 2018 GMT
Not After : Oct 30 12:00:00 2019 GMT
Subject: CN=Gitlab User, emailAddress=gitlab-user@example.com
```
### Authentication against a local database with X.509 certificates and SAN extension
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8605) in GitLab 12.3.
Smartcards with X.509 certificates using SAN extensions can be used to authenticate
with GitLab.
NOTE:
This is an experimental feature. Smartcard authentication against local databases may
change or be removed completely in future releases.
To use a smartcard with an X.509 certificate to authenticate against a local
database with GitLab, in:
- GitLab 12.4 and later, at least one of the `subjectAltName` (SAN) extensions
need to define the user identity (`email`) within the GitLab instance (`URI`).
`URI`: needs to match `Gitlab.config.host.gitlab`.
- From [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/-/issues/33907),
if your certificate contains only **one** SAN email entry, you don't need to
add or modify it to match the `email` with the `URI`.
For example:
```plaintext
Certificate:
Data:
Version: 1 (0x0)
Serial Number: 12856475246677808609 (0xb26b601ecdd555e1)
Signature Algorithm: sha256WithRSAEncryption
Issuer: O=Random Corp Ltd, CN=Random Corp
Validity
Not Before: Oct 30 12:00:00 2018 GMT
Not After : Oct 30 12:00:00 2019 GMT
...
X509v3 extensions:
X509v3 Key Usage:
Key Encipherment, Data Encipherment
X509v3 Extended Key Usage:
TLS Web Server Authentication
X509v3 Subject Alternative Name:
email:gitlab-user@example.com, URI:http://gitlab.example.com/
```
### Authentication against an LDAP server
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/7693) in GitLab 11.8 as an experimental feature. Smartcard authentication against an LDAP server may change or be removed completely in the future.
GitLab implements a standard way of certificate matching following
[RFC4523](https://www.rfc-editor.org/rfc/rfc4523). It uses the
`certificateExactMatch` certificate matching rule against the `userCertificate`
attribute. As a prerequisite, you must use an LDAP server that:
- Supports the `certificateExactMatch` matching rule.
- Has the certificate stored in the `userCertificate` attribute.
NOTE:
Active Directory doesn't support the `certificateExactMatch` matching rule so
[it is not supported at this time](https://gitlab.com/gitlab-org/gitlab/-/issues/327491). For
more information, see [the relevant issue](https://gitlab.com/gitlab-org/gitlab/-/issues/328074).
## Configure GitLab for smartcard authentication
For Linux package installations:
1. Edit `/etc/gitlab/gitlab.rb`:
```ruby
# Allow smartcard authentication
gitlab_rails['smartcard_enabled'] = true
# Path to a file containing a CA certificate
gitlab_rails['smartcard_ca_file'] = "/etc/ssl/certs/CA.pem"
# Host and port where the client side certificate is requested by the
# webserver (NGINX/Apache)
gitlab_rails['smartcard_client_certificate_required_host'] = "smartcard.example.com"
gitlab_rails['smartcard_client_certificate_required_port'] = 3444
```
NOTE:
Assign a value to at least one of the following variables:
`gitlab_rails['smartcard_client_certificate_required_host']` or
`gitlab_rails['smartcard_client_certificate_required_port']`.
1. Save the file and [reconfigure](../restart_gitlab.md#reconfigure-a-linux-package-installation)
GitLab for the changes to take effect.
For self-compiled installations:
1. Configure NGINX to request a client side certificate
In NGINX configuration, an **additional** server context must be defined with
the same configuration except:
- The additional NGINX server context must be configured to run on a different
port:
```plaintext
listen *:3444 ssl;
```
- It can also be configured to run on a different hostname:
```plaintext
listen smartcard.example.com:443 ssl;
```
- The additional NGINX server context must be configured to require the client
side certificate:
```plaintext
ssl_verify_depth 2;
ssl_client_certificate /etc/ssl/certs/CA.pem;
ssl_verify_client on;
```
- The additional NGINX server context must be configured to forward the client
side certificate:
```plaintext
proxy_set_header X-SSL-Client-Certificate $ssl_client_escaped_cert;
```
For example, the following is an example server context in an NGINX
configuration file (such as in `/etc/nginx/sites-available/gitlab-ssl`):
```plaintext
server {
listen smartcard.example.com:3443 ssl;
# certificate for configuring SSL
ssl_certificate /path/to/example.com.crt;
ssl_certificate_key /path/to/example.com.key;
ssl_verify_depth 2;
# CA certificate for client side certificate verification
ssl_client_certificate /etc/ssl/certs/CA.pem;
ssl_verify_client on;
location / {
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header X-SSL-Client-Certificate $ssl_client_escaped_cert;
proxy_read_timeout 300;
proxy_pass http://gitlab-workhorse;
}
}
```
1. Edit `config/gitlab.yml`:
```yaml
## Smartcard authentication settings
smartcard:
# Allow smartcard authentication
enabled: true
# Path to a file containing a CA certificate
ca_file: '/etc/ssl/certs/CA.pem'
# Host and port where the client side certificate is requested by the
# webserver (NGINX/Apache)
client_certificate_required_host: smartcard.example.com
client_certificate_required_port: 3443
```
NOTE:
Assign a value to at least one of the following variables:
`client_certificate_required_host` or `client_certificate_required_port`.
1. Save the file and [restart](../restart_gitlab.md#installations-from-source)
GitLab for the changes to take effect.
### Additional steps when using SAN extensions
For Linux package installations:
1. Add to `/etc/gitlab/gitlab.rb`:
```ruby
gitlab_rails['smartcard_san_extensions'] = true
```
1. Save the file and [reconfigure](../restart_gitlab.md#reconfigure-a-linux-package-installation)
GitLab for the changes to take effect.
For self-compiled installations:
1. Add the `san_extensions` line to `config/gitlab.yml` within the smartcard section:
```yaml
smartcard:
enabled: true
ca_file: '/etc/ssl/certs/CA.pem'
client_certificate_required_port: 3444
# Enable the use of SAN extensions to match users with certificates
san_extensions: true
```
1. Save the file and [restart](../restart_gitlab.md#installations-from-source)
GitLab for the changes to take effect.
### Additional steps when authenticating against an LDAP server
For Linux package installations:
1. Edit `/etc/gitlab/gitlab.rb`:
```ruby
gitlab_rails['ldap_servers'] = YAML.load <<-EOS
main:
# snip...
# Enable smartcard authentication against the LDAP server. Valid values
# are "false", "optional", and "required".
smartcard_auth: optional
EOS
```
1. Save the file and [reconfigure](../restart_gitlab.md#reconfigure-a-linux-package-installation)
GitLab for the changes to take effect.
For self-compiled installations:
1. Edit `config/gitlab.yml`:
```yaml
production:
ldap:
servers:
main:
# snip...
# Enable smartcard authentication against the LDAP server. Valid values
# are "false", "optional", and "required".
smartcard_auth: optional
```
1. Save the file and [restart](../restart_gitlab.md#installations-from-source)
GitLab for the changes to take effect.
### Require browser session with smartcard sign-in for Git access
For Linux package installations:
1. Edit `/etc/gitlab/gitlab.rb`:
```ruby
gitlab_rails['smartcard_required_for_git_access'] = true
```
1. Save the file and [reconfigure](../restart_gitlab.md#reconfigure-a-linux-package-installation)
GitLab for the changes to take effect.
For self-compiled installations:
1. Edit `config/gitlab.yml`:
```yaml
## Smartcard authentication settings
smartcard:
# snip...
# Browser session with smartcard sign-in is required for Git access
required_for_git_access: true
```
1. Save the file and [restart](../restart_gitlab.md#installations-from-source)
GitLab for the changes to take effect.
## Passwords for users created via smartcard authentication
The [Generated passwords for users created through integrated authentication](../../security/passwords_for_integrated_authentication_methods.md) guide provides an overview of how GitLab generates and sets passwords for users created via smartcard authentication.
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, for example `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->
|