diff options
Diffstat (limited to 'doc/integration/kerberos.md')
| -rw-r--r-- | doc/integration/kerberos.md | 98 |
1 files changed, 75 insertions, 23 deletions
diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md index 1a193deca18..50468443769 100644 --- a/doc/integration/kerberos.md +++ b/doc/integration/kerberos.md @@ -1,6 +1,6 @@ --- -stage: Create -group: Source Code +stage: Manage +group: Access info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" type: reference, how-to --- @@ -47,7 +47,7 @@ sudo chmod 0600 /etc/http.keytab ### Configure GitLab -**Installations from source** +#### Installations from source NOTE: **Note:** For source installations, make sure the `kerberos` gem group @@ -74,7 +74,7 @@ For source installations, make sure the `kerberos` gem group 1. [Restart GitLab](../administration/restart_gitlab.md#installations-from-source) for the changes to take effect. -**Omnibus package installations** +#### Omnibus package installations 1. Edit `/etc/gitlab/gitlab.rb`: @@ -91,23 +91,75 @@ GitLab 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. -## Creating and linking Kerberos accounts +#### Enable single sign-on -The Administrative user can navigate to **Admin > Users > Example User > Identities** -and attach a Kerberos account. Existing GitLab users can go to **Profile > Account** -and attach a Kerberos account. If you want to allow users without a GitLab -account to login, you should enable the option `allow_single_sign_on` as -described in the [Configure GitLab](#configure-gitlab) section. Then, the first -time a user signs in with Kerberos credentials, GitLab will create a new GitLab -user associated with the email, which is built from the Kerberos username and -realm. User accounts will be created automatically when authentication was -successful. +See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) +for initial settings to enable single sign-on and add Kerberos servers +as an identity provider. -## Linking Kerberos and LDAP accounts together +## Create and link Kerberos accounts -If your users log in with Kerberos, but you also have [LDAP integration](../administration/auth/ldap/index.md) -enabled, then your users will be automatically linked to their LDAP accounts on -first login. For this to work, some prerequisites must be met: +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. + +### Link a Kerberos account to an existing GitLab account + +If you're an administrator, you can link a Kerberos account to an +existing GitLab account. To do so: + +1. Navigate to **Admin Area > Overview > Users > Example User**. +1. Select the Identities tab. +1. Select 'Kerberos Spnego' in the 'Provider' dropdown box. +1. Make sure the **Identifier** corresponds to the Kerberos username. +1. Select **Save changes**. + +If you're not an administrator: + +1. Select your avatar in the upper-right corner, and select **Settings**. +1. Select Account. 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](#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 [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) 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. +1. For now, accept the default `block_auto_created_users` option, true. +1. 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: + + ```shell + 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. + Select **Admin Area > Overview > Users** and review the Blocked tab. + 1. You can enable the user. + 1. If `block_auto_created_users` is false, the Kerberos user is + authenticated and is signed in to GitLab. + +CAUTION: **Warning** +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. + +## Link Kerberos and LDAP accounts together + +If your users sign in with Kerberos, but you also have [LDAP integration](../administration/auth/ldap/index.md) +enabled, your users will be 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 GitLab's [LDAP configuration](../administration/auth/ldap/index.md#configuration) @@ -125,10 +177,10 @@ LDAP Distinguished Names look like `sAMAccountName=foo,dc=ad,dc=example,dc=com`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/9962) 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 will be ignored and an LDAP identity will not be linked. +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 will be +ignored and an LDAP identity won't be linked. **For Omnibus installations** @@ -164,7 +216,7 @@ GitLab 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. -DANGER: **Danger:** +DANGER: **Warning:** There is a [known issue](https://github.com/curl/curl/issues/1261) with `libcurl` older than version 7.64.1 wherein it won't reuse connections when negotiating. This leads to authorization issues when push is larger than `http.postBuffer` |