Kerberos integration

GitLab can integrate with Kerberos as an authentication mechanism.

caution
GitLab CI/CD doesn’t work with a Kerberos-enabled GitLab instance unless the integration is set to use a dedicated port.

Overview

Kerberos is a secure method for authenticating a request for a service in a computer network. Kerberos was developed in the Athena Project at the Massachusetts Institute of Technology (MIT). The name is taken from Greek mythology; Kerberos was a three-headed dog who guarded the gates of Hades.

Use-cases

  • GitLab can be configured to allow your users to sign with their Kerberos credentials.
  • You can use Kerberos to prevent anyone from intercepting or eavesdropping on the transmitted password.

Configuration

For GitLab to offer Kerberos token-based authentication, perform the following prerequisites. You still need to configure your system for Kerberos usage, such as specifying realms. GitLab makes use of the system’s Kerberos settings.

GitLab keytab

  1. Create a Kerberos Service Principal for the HTTP service on your GitLab server. If your GitLab server is gitlab.example.com and your Kerberos realm EXAMPLE.COM, create a Service Principal HTTP/gitlab.example.com@EXAMPLE.COM in your Kerberos database.
  2. Create a keytab on the GitLab server for the above Service Principal. For example, /etc/http.keytab.

The keytab is a sensitive file and must be readable by the GitLab user. Set ownership and protect the file appropriately:

sudo chown git /etc/http.keytab
sudo chmod 0600 /etc/http.keytab

Configure GitLab

Installations from source

note
For source installations, make sure the kerberos gem group has been installed.
  1. Edit the kerberos section of gitlab.yml to enable Kerberos ticket-based authentication. In most cases, you only need to enable Kerberos and specify the location of the keytab:

    omniauth:
      enabled: true
      allow_single_sign_on: ['kerberos']
    
    kerberos:
      # Allow the HTTP Negotiate authentication method for Git clients
      enabled: true
    
      # Kerberos 5 keytab file. The keytab file must be readable by the GitLab user,
      # and should be different from other keytabs in the system.
      # (default: use default keytab from Krb5 config)
      keytab: /etc/http.keytab
    
  2. Restart GitLab for the changes to take effect.

Omnibus package installations

  1. Edit /etc/gitlab/gitlab.rb:

    gitlab_rails['omniauth_allow_single_sign_on'] = ['kerberos']
    
    gitlab_rails['kerberos_enabled'] = true
    gitlab_rails['kerberos_keytab'] = "/etc/http.keytab"
    

    To avoid GitLab creating users automatically on their first sign in through Kerberos, don’t set kerberos for gitlab_rails['omniauth_allow_single_sign_on'].

  2. Reconfigure GitLab for the changes to take effect.

GitLab now offers the negotiate authentication method for signing in and HTTP Git access, enabling Git clients that support this authentication protocol to authenticate with Kerberos tokens.

Enable single sign-on

See Configure initial settings for initial settings to enable single sign-on and add Kerberos servers as an identity provider.

You can either link a Kerberos account to an existing GitLab account, or set up GitLab to create a new account when a Kerberos user tries to sign in.

If you’re an administrator, you can link a Kerberos account to an existing GitLab account. To do so:

  1. On the top bar, select Menu > Admin.
  2. On the left sidebar, select Overview > Users.
  3. Select a user, then select the Identities tab.
  4. Select ‘Kerberos SPNEGO’ in the ‘Provider’ dropdown box.
  5. Make sure the Identifier corresponds to the Kerberos username.
  6. Select Save changes.

If you’re not an administrator:

  1. In the top-right corner, select your avatar.
  2. Select Edit profile.
  3. On the left sidebar, select Account.
  4. In the Social sign-in section, select Connect Kerberos SPNEGO. If you don’t see a Social sign-in Kerberos option, follow the requirements in Enable single sign-on.

In either case, you should now be able to sign in to your GitLab account with your Kerberos credentials.

Create accounts on first sign-in

The first time users sign in to GitLab with their Kerberos accounts, GitLab creates a matching account. Before you continue, review the Configure initial settings options in Omnibus and GitLab source. You must also include kerberos.

With that information at hand:

  1. Include 'kerberos' with the allow_single_sign_on setting.
  2. For now, accept the default block_auto_created_users option, true.
  3. When a user tries to sign in with Kerberos credentials, GitLab creates a new account.
    1. If block_auto_created_users is true, the Kerberos user may see a message like:

      Your account has been blocked. Please contact your GitLab
      administrator if you think this is an error.
      
      1. As an administrator, you can confirm the new, blocked account:
        1. On the top bar, select Menu > Admin.
        2. On the left sidebar, select Overview > Users and review the Blocked tab.
      2. You can enable the user.
    2. If block_auto_created_users is false, the Kerberos user is authenticated and is signed in to GitLab.

caution
We recommend that you retain the default for block_auto_created_users. Kerberos users who create accounts on GitLab without administrator knowledge can be a security risk.

If your users sign in with Kerberos, but you also have LDAP integration enabled, your users are linked to their LDAP accounts on their first sign-in. For this to work, some prerequisites must be met:

The Kerberos username must match the LDAP user’s UID. You can choose which LDAP attribute is used as the UID in the GitLab LDAP configuration but for Active Directory, this should be sAMAccountName.

The Kerberos realm must match the domain part of the LDAP user’s Distinguished Name. For instance, if the Kerberos realm is AD.EXAMPLE.COM, then the LDAP user’s Distinguished Name should end in dc=ad,dc=example,dc=com.

Taken together, these rules mean that linking only works if your users’ Kerberos usernames are of the form foo@AD.EXAMPLE.COM and their LDAP Distinguished Names look like sAMAccountName=foo,dc=ad,dc=example,dc=com.

Custom allowed realms

Introduced in GitLab 13.5.

You can configure custom allowed realms when the user’s Kerberos realm doesn’t match the domain from the user’s LDAP DN. The configuration value must specify all domains that users may be expected to have. Any other domains are ignored and an LDAP identity is not linked.

For Omnibus installations

  1. Edit /etc/gitlab/gitlab.rb:

    gitlab_rails['kerberos_simple_ldap_linking_allowed_realms'] = ['example.com','kerberos.example.com']
    
  2. Save the file and reconfigure GitLab for the changes to take effect.


For installations from source

  1. Edit config/gitlab.yml:

    kerberos:
      simple_ldap_linking_allowed_realms: ['example.com','kerberos.example.com']
    
  2. Save the file and restart GitLab for the changes to take effect.

HTTP Git access

A linked Kerberos account enables you to git pull and git push using your Kerberos account, as well as your standard GitLab credentials.

GitLab users with a linked Kerberos account can also git pull and git push using Kerberos tokens. That is, without having to send their password with each operation.

caution
There is a known issue with libcurl older than version 7.64.1 wherein it doesn’t reuse connections when negotiating. This leads to authorization issues when push is larger than http.postBuffer configuration. Ensure that Git is using at least libcurl 7.64.1 to avoid this. To know the libcurl version installed, run curl-config --version.

HTTP Git access with Kerberos token (passwordless authentication)

Because of a bug in current Git versions, the git CLI command uses only the negotiate authentication method if the HTTP server offers it, even if this method fails (such as when the client does not have a Kerberos token). It is thus not possible to fall back to an embedded username and password (also known as basic) authentication if Kerberos authentication fails.

For GitLab users to be able to use either basic or negotiate authentication with current Git versions, it is possible to offer Kerberos ticket-based authentication on a different port (for example, 8443) while the standard port offers only basic authentication.

note
Git 2.4 and later supports falling back to basic authentication if the username and password is passed interactively or through a credentials manager. It fails to fall back when the username and password is passed as part of the URL instead. For example, this can happen in GitLab CI/CD jobs that authenticate with the CI/CD job token.

For source installations with HTTPS

  1. Edit the NGINX configuration file for GitLab (for example, /etc/nginx/sites-available/gitlab-ssl) and configure NGINX to listen to port 8443 in addition to the standard HTTPS port:

    server {
      listen 0.0.0.0:443 ssl;
      listen [::]:443 ipv6only=on ssl default_server;
      listen 0.0.0.0:8443 ssl;
      listen [::]:8443 ipv6only=on ssl;
    
  2. Update the kerberos section of gitlab.yml:

    kerberos:
      # Dedicated port: Git before 2.4 does not fall back to Basic authentication if Negotiate fails.
      # To support both Basic and Negotiate methods with older versions of Git, configure
      # nginx to proxy GitLab on an extra port (for example: 8443) and uncomment the following lines
      # to dedicate this port to Kerberos authentication. (default: false)
      use_dedicated_port: true
      port: 8443
      https: true
    
    </