gitlabhq/doc/integration/ldap.md

GitLab LDAP integration

GitLab can be configured to allow your users to sign with their LDAP credentials to integrate with e.g. Active Directory. To enable LDAP integration, edit gitlab.rb (omnibus-gitlab)` or gitlab.yml (source installations) on your GitLab server and restart GitLab.

The first time a user signs in with LDAP credentials, GitLab will create a new GitLab user associated with the LDAP Distinguished Name (DN) of the LDAP user.

GitLab user attributes such as nickname and email will be copied from the LDAP user entry.

Enabling LDAP sign-in for existing GitLab users

When a user signs in to GitLab with LDAP for the first time, and their LDAP email address is the primary email address of an existing GitLab user, then the LDAP DN will be associated with the existing user.

If the LDAP email attribute is not found in GitLab's database, a new user is created.

In other words, if an existing GitLab user wants to enable LDAP sign-in for themselves, they should check that their GitLab email address matches their LDAP email address, and then sign into GitLab via their LDAP credentials.

GitLab recognizes the following LDAP attributes as email addresses: mail, email and userPrincipalName.

If multiple LDAP email attributes are present, e.g. mail: foo@bar.com and email: foo@example.com, then the first attribute found wins -- in this case foo@bar.com.

LDAP group synchronization (GitLab Enterprise Edition)

LDAP group synchronization in GitLab Enterprise Edition allows you to synchronize the members of a GitLab group with one or more LDAP groups.

Setting up LDAP group synchronization

Suppose we want to synchronize the GitLab group 'example group' with the LDAP group 'Engineering'.

1. As an owner, go to the group settings page for 'example group'.

As an admin you can also go to the group edit page in the admin area.

2. Enter 'Engineering' as the LDAP Common Name (CN) in the 'LDAP Group cn' field.

3. Enter a default group access level in the 'LDAP Access' field; let's say Developer.

4. Click 'Add synchronization' to add the new LDAP group link.

Now every time a member of the 'Engineering' LDAP group signs in, they automatically become a Developer-level member of the 'example group' GitLab group. Users who are already signed in will see the change in membership after up to one hour.

Synchronizing with more than one LDAP group (GitLab EE 7.3 and newer)

If you want to add the members of LDAP group to your GitLab group you can add an additional LDAP group link. If you have two LDAP group links, e.g. 'cn=Engineering' at level 'Developer' and 'cn=QA' at level 'Reporter', and user Jane belongs to both the 'Engineering' and 'QA' LDAP groups, she will get the highest access level of the two, namely 'Developer'.

Locking yourself out of your own group

As an LDAP-enabled GitLab user, if you create a group and then set it to synchronize with an LDAP group you do not belong to, you will be removed from the grop as soon as the synchronization takes effect for you.

If you accidentally lock yourself out of your own GitLab group, ask a GitLab administrator to change the LDAP synchronization settings for your group.

Non-LDAP GitLab users

Your GitLab instance may have users on it for whom LDAP is not enabled. If this is the case, these users will not be affected by LDAP group synchronization settings: they will be neither added nor removed automatically.

ActiveDirectory nested group support

If you are using ActiveDirectory, it is possible to create nested LDAP groups: the 'Engineering' LDAP group may contain another LDAP group 'Software', with 'Software' containing LDAP users Alice and Bob. GitLab will recognize Alice and Bob as members of the 'Engineering' group.

Define GitLab admin status via LDAP

It is possible to configure GitLab Enterprise Edition (7.1 and newer) so that GitLab admin rights are bestowed on the members of a given LDAP group. GitLab administrator users who do not have LDAP enabled are not affected by the LDAP admin group feature.

Enabling the admin group feature

Below we assume that you have an LDAP group with the common name (CN) 'GitLab administrators' containing the users that should be GitLab administrators. We recommend that you keep a non-LDAP GitLab administrator user around on your GitLab instance in case you accidentally remove the admin status from your own LDAP-enabled GitLab user.

For omnibus-gitlab, add the following to /etc/gitlab/gitlab.rb and run gitlab-ctl reconfigure.

gitlab_rails['ldap_admin_group'] = 'GitLab administrators'

For installations from source, add the following setting in the 'ldap' section of gitlab.yml, and run service gitlab reload afterwards.

    admin_group: 'Gitlab administrators'

Synchronising user SSH keys with LDAP

It is possible to configure GitLab Enterprise Edition (7.1 and newer) so that users have their SSH public keys synchronised with an attribute in their LDAP object. Existing SSH public keys that are manually manged in GitLab are not affected by this feature.

Enabling the key synchronisation feature

Below we assume that you have LDAP users with an attribute 'sshpublickey' containing the users ssh public key.

For omnibus-gitlab, add the following to /etc/gitlab/gitlab.rb and run gitlab-ctl reconfigure.

gitlab_rails['ldap_sync_ssh_keys'] = 'sshpublickey'

For installations from source, add the following setting in the 'ldap' section of gitlab.yml, and run service gitlab reload afterwards.

    sync_ssh_keys: 'sshpublickey'

Using an LDAP filter to limit access to your GitLab server

If you want to limit all GitLab access to a subset of the LDAP users on your LDAP server you can set up an LDAP user filter. The filter must comply with RFC 4515.

# For omnibus-gitlab
gitlab_rails['ldap_user_filter'] = '(employeeType=developer)'

# For installations from source
production:
  ldap:
     user_filter: '(employeeType=developer)'

Tip: if you want to limit access to the nested members of an Active Directory group you can use the following syntax:

(memberOf:1.2.840.113556.1.4.1941:=CN=My Group,DC=Example,DC=com)

Please note that GitLab does not support the custom filter syntax used by omniauth-ldap.

Integrate GitLab with more than one LDAP server (Enterprise Edition)

Starting with GitLab Enterprise Edition 7.4 it is possible to give users from more than one LDAP server access to the same GitLab server.

Please use the following steps to enable support for multiple LDAP servers.

1. Check your GitLab version

Go to gitlab.example.com/help and verify you are running GitLab Enterprise Edition 7.4.0 or newer.

2. Make sure your GitLab server uses the new LDAP syntax

# For omnibus packages
sudo gitlab-rails runner 'puts (Gitlab.config.ldap["host"] ? :old_syntax : :new_syntax)'

# For installations from source
cd /home/git/gitlab
bundle exec rails runner -e production 'puts (Gitlab.config.ldap["host"] ? :old_syntax : :new_syntax)'

3. Migrate existing users and groups

After switching to the new LDAP configuration syntax there will be a mismatch between the LDAP provider linked to your GitLab users and groups and the new LDAP provider defined in GitLab's configuration. The following command will associate all existing legacy LDAP users and groups on your GitLab server with the first LDAP server listed in gitlab.rb (omnibus) or gitlab.yml.

# For omnibus packages
sudo gitlab-rake gitlab:migrate_ldap_providers

# For installations from source
cd /home/git/gitlab
sudo -u git -H bundle exec rake gitlab:migrate_ldap_providers RAILS_ENV=production

4. Add new LDAP servers

Now you can add new LDAP servers via /etc/gitlab/gitlab.rb (omnibus packages) or gitlab.yml (installations from source). Remember to run sudo gitlab-ctl reconfigure or sudo service gitlab reload for the new servers to become available.