summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorThong Kuah <tkuah@gitlab.com>2019-09-12 00:50:18 +0000
committerThong Kuah <tkuah@gitlab.com>2019-09-12 00:50:18 +0000
commita3d836c9f7814f3a3c3fb149d54239475eb9c027 (patch)
tree07569c6287a7d1f137af3c635a2def3bf33fbf3b
parent3c372d87a701b600f42fccbf4707eebd67ff7cac (diff)
parentca2123429ef4be250cde796cee5c8a8cec1aca42 (diff)
downloadgitlab-ce-a3d836c9f7814f3a3c3fb149d54239475eb9c027.tar.gz
Merge branch '8605-support-san-extension' into 'master'
Backport of ee/15773: Allow SmartCard authentication to use SAN extensions See merge request gitlab-org/gitlab-ce!32581
-rw-r--r--config/gitlab.yml.example4
-rw-r--r--doc/administration/auth/smartcard.md69
2 files changed, 73 insertions, 0 deletions
diff --git a/config/gitlab.yml.example b/config/gitlab.yml.example
index 87159b695f9..92674aafa90 100644
--- a/config/gitlab.yml.example
+++ b/config/gitlab.yml.example
@@ -718,6 +718,10 @@ production: &base
# Browser session with smartcard sign-in is required for Git access
# required_for_git_access: false
+ # Use X.509 SAN extensions certificates to identify GitLab users
+ # Add a subjectAltName to your certificates like: email:user
+ # san_extensions: true
+
## Kerberos settings
kerberos:
# Allow the HTTP Negotiate authentication method for Git clients
diff --git a/doc/administration/auth/smartcard.md b/doc/administration/auth/smartcard.md
index 4f236d1afb8..920a2f0b399 100644
--- a/doc/administration/auth/smartcard.md
+++ b/doc/administration/auth/smartcard.md
@@ -39,6 +39,45 @@ Certificate:
Subject: CN=Gitlab User, emailAddress=gitlab-user@example.com
```
+### Authentication against a local database with X.509 certificates and SAN extensions **(PREMIUM ONLY)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/8605) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.3.
+
+Smartcards with X.509 certificates using SAN extensions can be used to authenticate
+with GitLab.
+
+NOTE: **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, 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`.
+
+For example:
+
+```text
+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-ee/issues/7693) in
@@ -152,6 +191,36 @@ attribute. As a prerequisite, you must use an LDAP server that:
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 Omnibus installations**
+
+1. Add to `/etc/gitlab/gitlab.rb`:
+
+ ```ruby
+ gitlab_rails['smartcard_san_extensions'] = true
+ ```
+
+1. Save the file and [reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure)
+ GitLab for the changes to take effect.
+
+**For installations from source**
+
+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 Omnibus installations**