Integrate Gitlab with OpenLDAP for Authentication

This tutorial will take you through how to integrate Gitlab with OpenLDAP for authentication. Gitlab supports LDAP authentication.

In our previous tutorials, we learnt how to install Gitlab on Debian/Ubuntu;

Install Gitlab CE on Debian 11

Install Gitlab with SSL/TLS Certificate on Ubuntu 20.04

We also have tutorials on setting up OpenLDAP;

Install and Setup OpenLDAP Server on Debian 11

Install and Setup OpenLDAP on Rocky Linux 8

Integrate Gitlab with OpenLDAP for Authentication

Assuming you already have a Gitlab and OpenLDAP servers setup and running, let us proceed to see how we can integrate Gitlab with OpenLDAP for authentication.

Create Gitlab Users OpenLDAP Member Group

In order to ensure only specific users can login to the Gitlab server via OpenLDAP, we will create a member group on our OpenLDAP server.

How to create OpenLDAP member groups has been extensively described in the guide below;

How to Create OpenLDAP Member Groups

Let us assume we have the following users we want to allow them login to Gitlab server via OpenLDAP;

ldapsearch -H ldapi:/// -Y EXTERNAL -LLL -b "dc=ldapmaster,dc=kifarunix-demo,dc=com" uid=* dn -Q

dn: uid=johndoe,ou=people,dc=ldapmaster,dc=kifarunix-demo,dc=com

dn: uid=janedoe,ou=people,dc=ldapmaster,dc=kifarunix-demo,dc=com

Hence, create a group with any name of your preference. For example, let us create a group called gitlab.

In our current LDAP server, we have a Group OU, ou=groups,dc=ldapmaster,dc=kifarunix-demo,dc=com

To create a gitlab group and add the users, janedoe and johndoe, create an LDIF config file as shown below;

cat > gitlab-group.ldif << EOL
dn: cn=gitlab,ou=groups,dc=ldapmaster,dc=kifarunix-demo,dc=com
objectClass: groupOfNames
cn: gitlab
member: uid=johndoe,ou=people,dc=ldapmaster,dc=kifarunix-demo,dc=com
member: uid=janedoe,ou=people,dc=ldapmaster,dc=kifarunix-demo,dc=com
EOL

Update the above as per your organization’s OpenLDAP server setup.

Next, run the command below on the OpenLDAP server terminal to create the group alongside the members of that group.

ldapadd -Y EXTERNAL -H ldapi:/// -Q -f gitlab-group.ldif

Once the command has run, you can verify the group is available and members;

ldapsearch -H ldapi:/// -Y EXTERNAL -LLL -b "dc=ldapmaster,dc=kifarunix-demo,dc=com" cn=gitlab -Q

dn: cn=gitlab,ou=groups,dc=ldapmaster,dc=kifarunix-demo,dc=com
objectClass: groupOfNames
cn: gitlab
member: uid=johndoe,ou=people,dc=ldapmaster,dc=kifarunix-demo,dc=com
member: uid=janedoe,ou=people,dc=ldapmaster,dc=kifarunix-demo,dc=com

You can add more members to the group as described on the post above.

Integrate Gitlab with OpenLDAP for Authentication

Once you have setup OpenLDAP group and added members, you can now configure Gitlab to use OpenLDAP for authentication.

Open Gitlab configuration file for editing;

vim /etc/gitlab/gitlab.rb

Scroll down to LDAP settings configuration section;

By default, LDAP configuration settings are commented out;


### LDAP Settings
###! Docs: https://docs.gitlab.com/omnibus/settings/ldap.html
###! **Be careful not to break the indentation in the ldap_servers block. It is
###!   in yaml format and the spaces must be retained. Using tabs will not work.**
# gitlab_rails['ldap_enabled'] = false
# gitlab_rails['prevent_ldap_sign_in'] = false

###! **remember to close this block with 'EOS' below**
# gitlab_rails['ldap_servers'] = YAML.load <<-'EOS'
#   main: # 'main' is the GitLab 'provider ID' of this LDAP server
#     label: 'LDAP'
#     host: '_your_ldap_server'
#     port: 389
#     uid: 'sAMAccountName'
#     bind_dn: '_the_full_dn_of_the_user_you_will_bind_with'
#     password: '_the_password_of_the_bind_user'
#     encryption: 'plain' # "start_tls" or "simple_tls" or "plain"
#     verify_certificates: true
#     smartcard_auth: false
#     active_directory: true
#     allow_username_or_email_login: false
#     lowercase_usernames: false
#     block_auto_created_users: false
#     base: ''
#     user_filter: ''
#     ## EE only
#     group_base: ''
#     admin_group: ''
#     sync_ssh_keys: false
#
#   secondary: # 'secondary' is the GitLab 'provider ID' of second LDAP server
#     label: 'LDAP'
#     host: '_your_ldap_server'
#     port: 389
#     uid: 'sAMAccountName'
#     bind_dn: '_the_full_dn_of_the_user_you_will_bind_with'
#     password: '_the_password_of_the_bind_user'
#     encryption: 'plain' # "start_tls" or "simple_tls" or "plain"
#     verify_certificates: true
#     smartcard_auth: false
#     active_directory: true
#     allow_username_or_email_login: false
#     lowercase_usernames: false
#     block_auto_created_users: false
#     base: ''
#     user_filter: ''
#     ## EE only
#     group_base: ''
#     admin_group: ''
#     sync_ssh_keys: false
# EOS

We will update this configuration section such that it looks like;


### LDAP Settings

gitlab_rails['ldap_enabled'] = true
gitlab_rails['prevent_ldap_sign_in'] = false

gitlab_rails['ldap_servers'] = {
'main' => {
  'label' => 'LDAP',
  'host' =>  'ldap.kifarunix-demo.com',
  'port' => 389,
  'uid' => 'uid',
  'encryption' => 'start_tls',
  'verify_certificates' => false,
  'tls_options' => {
    'ca_file' => '/etc/ssl/certs/ldapca.pem'
   # 'ssl_version' => '',
   # 'ciphers' => '',
   # 'cert' => '',
   # 'key' => ''
  },
  'bind_dn' => 'cn=readonly,ou=system,dc=ldapmaster,dc=kifarunix-demo,dc=com',
  'password' => 'hacker',
  'timeout' => 10,
  'active_directory' => false,
  'allow_username_or_email_login' => true,
  'block_auto_created_users' => true,
  'base' => 'dc=ldapmaster,dc=kifarunix-demo,dc=com',
  'user_filter' => '(memberOf=cn=gitlab,ou=groups,dc=ldapmaster,dc=kifarunix-demo,dc=com)',
  'attributes' => {
    'username' => ['uid'],
    'email' => ['Email'],
    'name' => 'ui',
    'first_name' => 'cn',
    'last_name' => 'sn'
  },
  'lowercase_usernames' => false,

  # EE Only
  'group_base' => '',
  'admin_group' => '',
  'external_groups' => [],
  'sync_ssh_keys' => false
  }
}

Be sure to replace:

host: address of the LDAP server, IP or resolvable hostname
bind_dn: The DN of the LDAP user to bind with.

bind_dn password: The password of the bind user.
base: Base where to search for users.
user_filter: Filter to specify the users allowed to login to Gitlab via OpenLDAP. In our case it the group we created above.

The user attributes to match your LDAP setup.

NOTE for SSL configurations, we are using self-signed ssl for demo purposes. As such, we have set the verification to false.

Once you are done making changes to the configuration, reconfigure the Gitlab application.

gitlab-ctl reconfigure

Check the `bind_dn` and `password` credentials

Next, run the command below to "tests the bind_dn and password credentials (if configured) and lists a sample of LDAP users";

gitlab-rake gitlab:ldap:check

Sample output;

Checking LDAP ...

LDAP: ... Server: ldapmain
not verifying SSL hostname of LDAPS server 'ldap.kifarunix-demo.com:389'
LDAP authentication... Success
LDAP users with access to your GitLab server (only showing the first 100 results)
	DN: uid=johndoe,ou=people,dc=ldapmaster,dc=kifarunix-demo,dc=com	 uid: johndoe
	DN: uid=janedoe,ou=people,dc=ldapmaster,dc=kifarunix-demo,dc=com	 uid: janedoe

Checking LDAP ... Finished

Seems all is well, -:).

Login to Gitlab with OpenLDAP Credentials

Next, navigate to the Gitlab web interface. You will notice that on the login page, you have two options to login: LDAP and Standard.

Login with an LDAP user. If the user account has to be validated by the admin before one can login, then you will see such a message;

Your account is pending approval from your GitLab administrator and hence blocked. Please contact your GitLab administrator if you think this is an error.

Navigate to Admin > Users > Pending Approval. You should see the LDAP user account. Click on the gear button adjacent to the user and click Approve.