GitSwarm can be configured to allow your users to sign with their Kerberos credentials.
For GitSwarm to offer Kerberos token-based authentication, perform the following prerequisites. You still need to configure your system for Kerberos usage, such as specifying realms. GitSwarm will make use of the system's Kerberos settings.
gitswarm.example.com and your Kerberos realm EXAMPLE.COM, create a Service Principal HTTP/gitswarm.example.com@EXAMPLE.COM in your Kerberos database./etc/http.keytab.The keytab is a sensitive file and must be readable by the GitSwarm user. Set ownership and protect the file appropriately:
sudo chown git /etc/http.keytab
sudo chmod 0600 /etc/http.keytabInstallations from source
Note: For source installations, make sure the
kerberosgem group has been installed.
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 GitSwarm user,
# and should be different from other keytabs in the system.
# (default: use default keytab from Krb5 config)
keytab: /etc/http.keytab[Restart GitSwarm] for the changes to take effect.
package installation installations
Edit /etc/gitswarm/gitswarm.rb:
gitlab_rails['omniauth_enabled'] = true
gitlab_rails['omniauth_allow_single_sign_on'] = ['kerberos']
gitlab_rails['kerberos_enabled'] = true
gitlab_rails['kerberos_keytab'] = "/etc/http.keytab"[Reconfigure GitSwarm] for the changes to take effect.
GitSwarm will now offer the negotiate authentication method for signing in and HTTP Git access, enabling Git clients that support this authentication protocol to authenticate with Kerberos tokens.
The Administrative user can navigate to Admin > Users > Example User > Identities and attach a Kerberos account. Existing GitSwarm users can go to Profile > Account and attach a Kerberos account. If you want to allow users without a GitSwarm account to login, you should enable the option allow_single_sign_on as described in the Configure GitSwarm section. Then, the first time a user signs in with Kerberos credentials, GitSwarm will create a new GitSwarm user associated with the email, which is built from the Kerberos username and realm. User accounts will be created automatically when authentication was successful.
A linked Kerberos account enables you to git pull and git push using your Kerberos account, as well as your standard GitSwarm credentials.
GitSwarm users with a linked Kerberos account can also git pull and git push using Kerberos tokens, i.e., without having to send their password with each operation.
Until Git version 2.4, the git 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 username/password (also known as basic) authentication if Kerberos authentication fails.
For GitSwarm users to be able to use either basic or negotiate authentication with older Git versions, it is possible to offer Kerberos ticket-based authentication on a different port (e.g. 8443) while the standard port will keep offering only basic authentication.
For source installations with HTTPS
Edit the NGINX configuration file for GitSwarm (e.g., /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;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 GitSwarm on an extra port (e.g. 8443) and uncomment the following lines
# to dedicate this port to Kerberos authentication. (default: false)
use_dedicated_port: true
port: 8443
https: true[Restart GitSwarm] and NGINX for the changes to take effect.
For package installation installations
Edit /etc/gitswarm/gitswarm.rb:
gitlab_rails['kerberos_use_dedicated_port'] = true
gitlab_rails['kerberos_port'] = 8443
gitlab_rails['kerberos_https'] = true[Reconfigure GitSwarm] for the changes to take effect.
After this change, all Git remote URLs will have to be updated to https://gitswarm.example.com:8443/mygroup/myproject.git in order to use Kerberos ticket-based authentication.
Prior to GitSwarm 2016.3 Enterprise Edition, users had to submit their Kerberos username and password to GitSwarm 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 GitSwarm configuration, the 'Sign in with: Kerberos Spnego' button may already be visible on your GitSwarm sign-in page. If not, then add the settings described above.
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 / /etc/gitswarm/gitswarm.rb file.
For source installations
Edit gitlab.yml and remove the - { name: 'kerberos' } line under omniauth providers:
omniauth:
# ...
providers:
- { name: 'kerberos' } # <-- remove this line[Restart GitSwarm] for the changes to take effect.
For package installations
Edit /etc/gitswarm/gitswarm.rb and remove the { "name" => "kerberos" } line under gitlab_rails['omniauth_providers']:
gitlab_rails['omniauth_providers'] = [
{ "name" => "kerberos" } # <-- remove this entry
][Reconfigure GitSwarm] for the changes to take effect.
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.