PageRenderTime 40ms CodeModel.GetById 15ms RepoModel.GetById 0ms app.codeStats 0ms

Markdown | 304 lines | 223 code | 81 blank | 0 comment | 0 complexity | 32471c38e087d3c5c1f40cddce921dec MD5 | raw file
  1. # Kerberos integration **(STARTER ONLY)**
  2. GitLab can integrate with [Kerberos][kerb] as an authentication mechanism.
  3. ## Overview
  4. [Kerberos][kerb] is a secure method for authenticating a request for a service in a
  5. computer network. Kerberos was developed in the Athena Project at the
  6. [Massachusetts Institute of Technology (MIT)][mit]. The name is taken from Greek
  7. mythology; Kerberos was a three-headed dog who guarded the gates of Hades.
  8. ## Use-cases
  9. - GitLab can be configured to allow your users to sign with their Kerberos credentials.
  10. - You can use Kerberos to [prevent][why-kerb] anyone from intercepting or eavesdropping on the transmitted password.
  11. ## Configuration
  12. For GitLab to offer Kerberos token-based authentication, perform the
  13. following prerequisites. You still need to configure your system for
  14. Kerberos usage, such as specifying realms. GitLab will make use of the
  15. system's Kerberos settings.
  16. ### GitLab keytab
  17. 1. Create a Kerberos Service Principal for the HTTP service on your GitLab server.
  18. If your GitLab server is `` and your Kerberos realm
  19. `EXAMPLE.COM`, create a Service Principal `HTTP/`
  20. in your Kerberos database.
  21. 1. Create a keytab on the GitLab server for the above Service Principal, e.g.
  22. `/etc/http.keytab`.
  23. The keytab is a sensitive file and must be readable by the GitLab user. Set
  24. ownership and protect the file appropriately:
  25. ```
  26. sudo chown git /etc/http.keytab
  27. sudo chmod 0600 /etc/http.keytab
  28. ```
  29. ### Configure GitLab
  30. **Installations from source**
  31. >**Note:**
  32. For source installations, make sure the `kerberos` gem group
  33. [has been installed](../install/
  34. 1. Edit the `kerberos` section of [`gitlab.yml`]( to enable Kerberos ticket-based
  35. authentication. In most cases, you only need to enable Kerberos and specify
  36. the location of the keytab:
  37. ```yaml
  38. omniauth:
  39. enabled: true
  40. allow_single_sign_on: ['kerberos']
  41. kerberos:
  42. # Allow the HTTP Negotiate authentication method for Git clients
  43. enabled: true
  44. # Kerberos 5 keytab file. The keytab file must be readable by the GitLab user,
  45. # and should be different from other keytabs in the system.
  46. # (default: use default keytab from Krb5 config)
  47. keytab: /etc/http.keytab
  48. ```
  49. 1. [Restart GitLab] for the changes to take effect.
  50. **Omnibus package installations**
  51. 1. Edit `/etc/gitlab/gitlab.rb`:
  52. ```ruby
  53. gitlab_rails['omniauth_enabled'] = true
  54. gitlab_rails['omniauth_allow_single_sign_on'] = ['kerberos']
  55. gitlab_rails['kerberos_enabled'] = true
  56. gitlab_rails['kerberos_keytab'] = "/etc/http.keytab"
  57. ```
  58. 1. [Reconfigure GitLab] for the changes to take effect.
  59. GitLab will now offer the `negotiate` authentication method for signing in and
  60. HTTP Git access, enabling Git clients that support this authentication protocol
  61. to authenticate with Kerberos tokens.
  62. ## Creating and linking Kerberos accounts
  63. The Administrative user can navigate to **Admin > Users > Example User > Identities**
  64. and attach a Kerberos account. Existing GitLab users can go to **Profile > Account**
  65. and attach a Kerberos account. If you want to allow users without a GitLab
  66. account to login, you should enable the option `allow_single_sign_on` as
  67. described in the [Configure GitLab](#configure-gitlab) section. Then, the first
  68. time a user signs in with Kerberos credentials, GitLab will create a new GitLab
  69. user associated with the email, which is built from the Kerberos username and
  70. realm. User accounts will be created automatically when authentication was
  71. successful.
  72. ## Linking Kerberos and LDAP accounts together
  73. If your users log in with Kerberos, but you also have [LDAP integration](../administration/auth/
  74. enabled, then your users will be automatically linked to their LDAP accounts on
  75. first login. For this to work, some prerequisites must be met:
  76. The Kerberos username must match the LDAP user's UID. You can choose which LDAP
  77. attribute is used as the UID in GitLab's [LDAP configuration](../administration/auth/
  78. but for Active Directory, this should be `sAMAccountName`.
  79. The Kerberos realm must match the domain part of the LDAP user's Distinguished
  80. Name. For instance, if the Kerberos realm is `AD.EXAMPLE.COM`, then the LDAP
  81. user's Distinguished Name should end in `dc=ad,dc=example,dc=com`.
  82. Taken together, these rules mean that linking will only work if your users'
  83. Kerberos usernames are of the form `foo@AD.EXAMPLE.COM` and their
  84. LDAP Distinguished Names look like `sAMAccountName=foo,dc=ad,dc=example,dc=com`.
  85. ## HTTP Git access
  86. A linked Kerberos account enables you to `git pull` and `git push` using your
  87. Kerberos account, as well as your standard GitLab credentials.
  88. GitLab users with a linked Kerberos account can also `git pull` and `git push`
  89. using Kerberos tokens, i.e., without having to send their password with each
  90. operation.
  91. ### HTTP Git access with Kerberos token (passwordless authentication)
  92. #### Support for Git before 2.4
  93. Until Git version 2.4, the `git` command uses only the `negotiate` authentication
  94. method if the HTTP server offers it, even if this method fails (such as when
  95. the client does not have a Kerberos token). It is thus not possible to fall back
  96. to username/password (also known as `basic`) authentication if Kerberos
  97. authentication fails.
  98. For GitLab users to be able to use either `basic` or `negotiate` authentication
  99. with older Git versions, it is possible to offer Kerberos ticket-based
  100. authentication on a different port (e.g. 8443) while the standard port will
  101. keep offering only `basic` authentication.
  102. **For source installations with HTTPS**
  103. 1. Edit the NGINX configuration file for GitLab
  104. (e.g., `/etc/nginx/sites-available/gitlab-ssl`) and configure NGINX to
  105. listen to port `8443` in addition to the standard HTTPS port:
  106. ```conf
  107. server {
  108. listen ssl;
  109. listen [::]:443 ipv6only=on ssl default_server;
  110. listen ssl;
  111. listen [::]:8443 ipv6only=on ssl;
  112. ```
  113. 1. Update the `kerberos` section of [`gitlab.yml`](
  114. ```yaml
  115. kerberos:
  116. # Dedicated port: Git before 2.4 does not fall back to Basic authentication if Negotiate fails.
  117. # To support both Basic and Negotiate methods with older versions of Git, configure
  118. # nginx to proxy GitLab on an extra port (e.g. 8443) and uncomment the following lines
  119. # to dedicate this port to Kerberos authentication. (default: false)
  120. use_dedicated_port: true
  121. port: 8443
  122. https: true
  123. ```
  124. 1. [Restart GitLab] and NGINX for the changes to take effect.
  125. **For Omnibus package installations**
  126. 1. Edit `/etc/gitlab/gitlab.rb`:
  127. ```ruby
  128. gitlab_rails['kerberos_use_dedicated_port'] = true
  129. gitlab_rails['kerberos_port'] = 8443
  130. gitlab_rails['kerberos_https'] = true
  131. ```
  132. 1. [Reconfigure GitLab] for the changes to take effect.
  133. After this change, all Git remote URLs will have to be updated to
  134. `` in order to use
  135. Kerberos ticket-based authentication.
  136. ## Upgrading from password-based to ticket-based Kerberos sign-ins
  137. Prior to GitLab 8.10 Enterprise Edition, users had to submit their
  138. Kerberos username and password to GitLab when signing in. We will
  139. remove support for password-based Kerberos sign-ins in a future
  140. release, so we recommend that you upgrade to ticket-based sign-ins.
  141. Depending on your existing GitLab configuration, the 'Sign in with:
  142. Kerberos Spnego' button may already be visible on your GitLab sign-in
  143. page. If not, then add the settings [described above](#configuration).
  144. Once you have verified that the 'Kerberos Spnego' button works
  145. without entering any passwords, you can proceed to disable
  146. password-based Kerberos sign-ins. To do this you need only need to
  147. remove the OmniAuth provider named `kerberos` from your `gitlab.yml` /
  148. `gitlab.rb` file.
  149. **For installations from source**
  150. 1. Edit [`gitlab.yml`]( and remove the `- { name: 'kerberos' }` line under OmniAuth
  151. providers:
  152. ```yaml
  153. omniauth:
  154. # ...
  155. providers:
  156. - { name: 'kerberos' } # <-- remove this line
  157. ```
  158. 1. [Restart GitLab] for the changes to take effect.
  159. **For Omnibus installations**
  160. 1. Edit `/etc/gitlab/gitlab.rb` and remove the `{ "name" => "kerberos" }` line
  161. under `gitlab_rails['omniauth_providers']`:
  162. ```ruby
  163. gitlab_rails['omniauth_providers'] = [
  164. { "name" => "kerberos" } # <-- remove this entry
  165. ]
  166. ```
  167. 1. [Reconfigure GitLab] for the changes to take effect.
  168. ## Support for Active Directory Kerberos environments
  169. When using Kerberos ticket-based authentication in an Active Directory domain,
  170. it may be necessary to increase the maximum header size allowed by NGINX,
  171. as extensions to the Kerberos protocol may result in HTTP authentication headers
  172. larger than the default size of 8kB. Configure `large_client_header_buffers`
  173. to a larger value in [the NGINX configuration][nginx].
  174. ## Troubleshooting
  175. ### Unsupported GSSAPI mechanism
  176. With Kerberos SPNEGO authentication, the browser is expected to send a list of
  177. mechanisms it supports to GitLab. If it doesn't support any of the mechanisms
  178. GitLab supports, authentication will fail with a message like this in the log:
  179. ```
  180. OmniauthKerberosSpnegoController: failed to process Negotiate/Kerberos authentication: gss_accept_sec_context did not return GSS_S_COMPLETE: An unsupported mechanism was requested Unknown error
  181. ```
  182. This is usually seen when the browser is unable to contact the Kerberos server
  183. directly. It will fall back to an unsupported mechanism known as
  184. [`IAKERB`](, which tries to use
  185. the GitLab server as an intermediary to the Kerberos server.
  186. If you're experiencing this error, ensure there is connectivity between the
  187. client machine and the Kerberos server - this is a prerequisite! Traffic may be
  188. blocked by a firewall, or the DNS records may be incorrect.
  189. Another failure mode occurs when the forward and reverse DNS records for the
  190. GitLab server do not match. Often, Windows clients will work in this case, while
  191. Linux clients will fail. They use reverse DNS while detecting the Kerberos
  192. realm. If they get the wrong realm, then ordinary Kerberos mechanisms will fail,
  193. so the client will fall back to attempting to negotiate `IAKERB`, leading to the
  194. above error message.
  195. To fix this, ensure that the forward and reverse DNS for your GitLab server
  196. match. So for instance, if you acces GitLab as ``, resolving
  197. to IP address ``, then `` must be a PTR record for
  198. ``.
  199. Finally, it's possible that the browser or client machine lack Kerberos support
  200. completely. Ensure that the Kerberos libraries are installed and that you can
  201. authenticate to other Kerberos services.
  202. ### HTTP Basic: Access denied when cloning
  203. ```sh
  204. remote: HTTP Basic: Access denied
  205. fatal: Authentication failed for '<KRB5 path>'
  206. ```
  207. If you are using Git v2.11 or newer and see the above error when cloning, you can
  208. set the `http.emptyAuth` Git option to `true` to fix this:
  209. ```
  210. git config --global http.emptyAuth true
  211. ```
  212. See also: [Git v2.11 release notes](
  213. ## Helpful links
  214. - <>
  215. - <>
  216. - <>
  217. [restart gitlab]: ../administration/
  218. [reconfigure gitlab]: ../administration/
  219. [nginx]:
  220. [kerb]:
  221. [mit]:
  222. [why-kerb]:
  223. [ee]: