1. [Reconfigure GitLab] for the changes to take effect.
---
After this change, all Git remote URLs will have to be updated to
`https://gitlab.example.com:8443/mygroup/myproject.git` in order to use
Kerberos ticket-based authentication.
## Upgrading from password-based to ticket-based Kerberos sign-ins
Prior to GitLab 8.10 Enterprise Edition, users had to submit their
Kerberos username and password to GitLab when signing in. We will
remove support for password-based Kerberos sign-ins in a future
release, so we recommend that you upgrade to ticket-based sign-ins.
Depending on your existing GitLab configuration, the 'Sign in with:
Kerberos Spnego' button may already be visible on your GitLab sign-in
page. If not, then add the settings [described above](#configuration).
Once you have verified that the 'Kerberos Spnego' button works
without entering any passwords, you can proceed to disable
password-based Kerberos sign-ins. To do this you need only need to
remove the OmniAuth provider named `kerberos` from your `gitlab.yml` /
`gitlab.rb` file.
**For installations from source**
1. Edit [gitlab.yml] and remove the `- { name: 'kerberos' }` line under omniauth
providers:
```yaml
omniauth:
# ...
providers:
- { name: 'kerberos' } # <--removethisline
```
1. [Restart GitLab] for the changes to take effect.
---
**For Omnibus installations**
1. Edit `/etc/gitlab/gitlab.rb` and remove the `{ "name" => "kerberos" }` line
under `gitlab_rails['omniauth_providers']`:
```ruby
gitlab_rails['omniauth_providers'] = [
{ "name" => "kerberos" } # <--removethisentry
]
```
1. [Reconfigure GitLab] for the changes to take effect.
## Support for Active Directory Kerberos environments
When using Kerberos ticket-based authentication in an Active Directory domain,
it may be necessary to increase the maximum header size allowed by NGINX,
as extensions to the Kerberos protocol may result in HTTP authentication headers
larger than the default size of 8kB. Configure `large_client_header_buffers`
to a larger value in [the NGINX configuration][nginx].
## Troubleshooting
### 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 will fail with a message like this in the log:
```
OmniauthKerberosSpnegoController: failed to process Negotiate/Kerberos authentication: gss_accept_sec_context did not return GSS_S_COMPLETE: An unsupported mechanism was requested Unknown error
```
This is usually seen when the browser is unable to contact the Kerberos server
directly. It will fall back to an unsupported mechanism known as
[`IAKERB`](https://k5wiki.kerberos.org/wiki/Projects/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.
Another failure mode occurs when the forward and reverse DNS records for the
GitLab server do not match. Often, Windows clients will work in this case, while
Linux clients will fail. They use reverse DNS while detecting the Kerberos
realm. If they get the wrong realm, then ordinary Kerberos mechanisms will fail,
so the client will fall 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 acces GitLab as `gitlab.example.com`, resolving
to IP address `1.2.3.4`, then `4.3.2.1.in-addr.arpa` must be a PTR record for
`gitlab.example.com`.
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
```sh
remote: HTTP Basic: Access denied
fatal: Authentication failed for '<KRB5path>'
```
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
```
See also: [Git v2.11 release notes](https://github.com/git/git/blob/master/Documentation/RelNotes/2.11.0.txt#L482-L486)