smartcard.md 3.71 KB
Newer Older
1 2 3
# Smartcard authentication

> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/726) in
4
[GitLab Premium](https://about.gitlab.com/pricing/) 11.6 as an experimental
5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
feature. Smartcard authentication may change or be removed completely in future
releases.

Smartcards with X.509 certificates can be used to authenticate with GitLab.

## X.509 certificates

To use a smartcard with an X.509 certificate to authenticate with GitLab, `CN`
and `emailAddress` must be defined in the certificate. For example:

```
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
```

28
## Configure GitLab for smartcard authentication
29

30
**For Omnibus installations**
31

32
1. Edit `/etc/gitlab/gitlab.rb`:
33

34 35 36 37 38
    ```ruby
    gitlab_rails['smartcard_enabled'] = true
    gitlab_rails['smartcard_ca_file'] = "/etc/ssl/certs/CA.pem"
    gitlab_rails['smartcard_client_certificate_required_port'] = 3444
    ```
39

40
1. Save the file and [reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure)
41
   GitLab for the changes to take effect.
42

43
---
44

45
**For installations from source**
46

47
1. Configure NGINX to request a client side certificate
48

49 50
   In NGINX configuration, an **additional** server context must be defined with
   the same configuration except:
51

52 53
   - The additional NGINX server context must be configured to run on a different
     port:
54

55 56 57
     ```
     listen *:3444 ssl;
     ```
58

59 60
   - The additional NGINX server context must be configured to require the client
     side certificate:
61

62 63 64 65 66
     ```
     ssl_verify_depth 2;
     ssl_client_certificate /etc/ssl/certs/CA.pem;
     ssl_verify_client on;
     ```
67

68 69
   - The additional NGINX server context must be configured to forward the client
     side certificate:
70

71 72 73
     ```
     proxy_set_header    X-SSL-Client-Certificate    $ssl_client_escaped_cert;
     ```
74

75 76
   For example, the following is an example server context in an NGINX
   configuration file (eg. in `/etc/nginx/sites-available/gitlab-ssl`):
77

78 79 80
   ```
   server {
       listen *:3444 ssl;
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
       # 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;
       }
   }
   ```
107 108 109

1. Edit `config/gitlab.yml`:

110 111 112 113 114
   ```yaml
   ## Smartcard authentication settings
   smartcard:
     # Allow smartcard authentication
     enabled: true
115

116 117
     # Path to a file containing a CA certificate
     ca_file: '/etc/ssl/certs/CA.pem'
118

119 120 121
     # Port where the client side certificate is requested by NGINX
     client_certificate_required_port: 3444
   ```
122

123
1. Save the file and [restart](../restart_gitlab.md#installations-from-source)
124
   GitLab for the changes to take effect.