Troubleshooting GitLab with Kerberos integration

Tier: Free, Premium, Ultimate Offering: Self-managed

When working with GitLab with Kerberos integration, you might encounter the following issues.

Using Google Chrome with Kerberos authentication against Windows AD

When you use Google Chrome to sign in to GitLab with Kerberos, you must enter your full username. For example, username@domain.com.

If you do not enter your full username, the sign-in fails. Check the logs to see the following event message as evidence of this sign-in failure: 

"message":"OmniauthKerberosController: failed to process Negotiate/Kerberos authentication: gss_accept_sec_context did not return GSS_S_COMPLETE: An unsupported mechanism was requested\nUnknown error".

Test connectivity between the GitLab and Kerberos servers

You can use utilities like kinit and klist to test connectivity between the GitLab server and the Kerberos server. How you install these depends on your specific OS.

Use klist to see the service principal names (SPN) available in your keytab file and the encryption type for each SPN: 

klist -ke /etc/http.keytab

On an Ubuntu server, the output would look similar to the following: 

Keytab name: FILE:/etc/http.keytab
KVNO Principal
---- --------------------------------------------------------------------------
   3 HTTP/my.gitlab.domain@MY.REALM (des-cbc-crc)
   3 HTTP/my.gitlab.domain@MY.REALM (des-cbc-md5)
   3 HTTP/my.gitlab.domain@MY.REALM (arcfour-hmac)
   3 HTTP/my.gitlab.domain@MY.REALM (aes256-cts-hmac-sha1-96)
   3 HTTP/my.gitlab.domain@MY.REALM (aes128-cts-hmac-sha1-96)

Use kinit in verbose mode to test whether GitLab can use the keytab file to connect to the Kerberos server: 

KRB5_TRACE=/dev/stdout kinit -kt /etc/http.keytab HTTP/my.gitlab.domain@MY.REALM

This command shows a detailed output of the authentication process.

Unsupported GSSAPI mechanism

With Kerberos SPNEGO authentication, the browser is expected to send a list of mechanisms it supports to GitLab. If it doesn’t support any of the mechanisms GitLab supports, authentication fails with a message like this in the log: 

OmniauthKerberosController: failed to process Negotiate/Kerberos authentication: gss_accept_sec_context did not return GSS_S_COMPLETE: An unsupported mechanism was requested Unknown error

There are a number of potential causes and solutions for this error message.

Kerberos integration not using a dedicated port

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

Lack of connectivity between client machine and Kerberos server

This is usually seen when the browser is unable to contact the Kerberos server directly. It falls back to an unsupported mechanism known as IAKERB, which tries to use the GitLab server as an intermediary to the Kerberos server.

If you’re experiencing this error, ensure there is connectivity between the client machine and the Kerberos server - this is a prerequisite! Traffic may be blocked by a firewall, or the DNS records may be incorrect.

GitLab DNS record is a CNAME record error

Kerberos fails with this error when GitLab is referenced with a CNAME record. To resolve this issue, ensure the DNS record for GitLab is an A record.

Mismatched forward and reverse DNS records for GitLab instance hostname

Another failure mode occurs when the forward and reverse DNS records for the GitLab server do not match. Often, Windows clients work in this case while Linux clients fail. They use reverse DNS while detecting the Kerberos realm. If they get the wrong realm then ordinary Kerberos mechanisms fail, so the client falls back to attempting to negotiate IAKERB, leading to the above error message.

To fix this, ensure that the forward and reverse DNS for your GitLab server match. So for instance, if you access GitLab as gitlab.example.com, resolving to IP address 10.0.2.2, then 2.2.0.10.in-addr.arpa must be a PTR record for gitlab.example.com.

Missing Kerberos libraries on browser or client machine

Finally, it’s possible that the browser or client machine lack Kerberos support completely. Ensure that the Kerberos libraries are installed and that you can authenticate to other Kerberos services.

HTTP Basic: Access denied when cloning 

remote: HTTP Basic: Access denied
fatal: Authentication failed for '<KRB5 path>'

If you are using Git v2.11 or newer and see the above error when cloning, you can set the http.emptyAuth Git option to true to fix this: 

git config --global http.emptyAuth true

Git cloning with Kerberos over proxied HTTPS

You must comment the following if:

  • You see http:// URLs in the Clone with KRB5 Git Cloning options, when https:// URLs are expected.
  • HTTPS is not terminated at your GitLab instance, but is instead proxied by your load balancer or local traffic manager. 
# gitlab_rails['kerberos_https'] = false

See also: Git v2.11 release notes