Connect GitLab to LDAP

Connect GitLab to LDAP, configure secure binds and user filters, map groups, test synchronization, and troubleshoot authentication failures.

Type
Tutorial
Level
Intermediate
Technologies
LDAP, LDAPS
On this page

Introduction: Why Integrate LDAP with GitLab?

Integrating LDAP with GitLab allows organizations to centralize authentication, streamline user management, and inherit enterprise access policies. By connecting GitLab to an existing directory service—such as Active Directory, OpenLDAP, or compatible products—teams can ensure that only authorized users can sign in, and that user sessions, group memberships, and account permissions are always in sync with the directory’s state.

LDAP integration is supported for self-managed GitLab instances (Community, Premium, and Ultimate)—not on GitLab SaaS (GitLab.com). This article provides a complete, technically precise guide aimed at identity engineers, GitLab administrators, and DevOps teams who need a reliable, secure, and maintainable directory connection.

Understanding GitLab LDAP Authentication and User Lifecycle

When LDAP integration is enabled, the authentication flow during GitLab sign-in is as follows:

  • The user enters their LDAP credentials on the GitLab sign-in page.
  • GitLab attempts to bind to the LDAP directory using a service account (if bind_dn is configured) or anonymously.
  • GitLab searches for the user in LDAP using the specified base and user_filter. If a matching LDAP entry is found, GitLab binds as that user to verify the password.
  • If the LDAP user’s email or external UID matches an existing GitLab account, they are linked. If not, a new GitLab user account is created for them on first sign-in, using mapped LDAP attributes (such as email, name, and username).
  • On subsequent logins or periodic syncs, if the user no longer matches the filter or is removed/disabled from LDAP, GitLab sets their account status to ldap_blocked—denying access.

This integration ensures GitLab users stay aligned with directory state: deprovisioning or changes in LDAP propagate automatically, maintaining access control without duplicate user management.

Preparing for Integration: Pre-requisites and Compatibility

Before configuration, verify the following prerequisites:

  • Self-managed GitLab Required: LDAP integration is available in all self-managed GitLab tiers (Community/Free, Premium, Ultimate). It is not available on GitLab SaaS (GitLab.com).
  • Supported Directories: GitLab supports Active Directory, OpenLDAP, Apple Open Directory, 389 Server, and compatible LDAP implementations.
  • Service Account: Obtain a dedicated LDAP service account (bind_dn) with sufficient permissions to search users and, if group restrictions are used, enumerate group memberships. Read-only permissions are usually sufficient and recommended.
  • LDAP Details Needed: Collect the LDAP server’s URL/hostname, port, encryption requirements (e.g., start_tls or simple_tls), base DN for searches, and any group DNs for access restriction.
  • Access and Network: Ensure the GitLab instance (typically Omnibus-based) can reach the LDAP server network and port, and that firewall rules permit communication.

Step-by-Step GitLab LDAP Configuration

LDAP is configured in /etc/gitlab/gitlab.rb using a YAML block within gitlab_rails['ldap_servers']. Enabling LDAP requires:

  • Setting gitlab_rails['ldap_enabled'] = true
  • Defining at least one LDAP server configuration within gitlab_rails['ldap_servers']

A minimal example:

ruby
gitlab_rails['ldap_enabled'] = true
gitlab_rails['ldap_servers'] = {
  'main' => {
    'label' => 'LDAP',
    'host' => '_your_ldap_server_',
    'port' => 389,
    'uid' => 'sAMAccountName',
    'encryption' => 'start_tls',
    'bind_dn' => 'CN=gitlab-bind,CN=Users,DC=example,DC=com',
    'password' => '_your_password_',
    'base' => 'CN=Users,DC=example,DC=com',
    'user_filter' => '',
    'active_directory' => true,
    'allow_username_or_email_login' => true,
    'lowercase_usernames' => false,
    'block_auto_created_users' => false,
    'attributes' => {
      'username' => ['sAMAccountName'],
      'email' =>    ['mail', 'userPrincipalName'],
      'name' =>       'cn',
      'first_name' => 'givenName',
      'last_name' =>  'sn'
    }
  }
}

Required fields:
host, port, uid, encryption, base (the LDAP DN at which user searches begin), and appropriate bind_dn/password for authenticated binds.

Indentation and YAML:
This section is indentation-sensitive and must use spaces (never tabs). Incorrect indentation, use of tabs, or JSON/YAML syntax errors will prevent LDAP from working and may not yield obvious startup errors.

Restricting by LDAP Group:
To control who may access GitLab, use a user_filter. For example, to limit sign-in to members of a group gitlabusers:

ruby
'user_filter' => '(memberof=CN=gitlabusers,CN=Groups,DC=example,DC=com)'

This ensures only users matching the filter can authenticate and are kept synchronized.

Attribute Mapping:
Control which LDAP attributes map to GitLab user fields by editing the attributes subsection, matching your directory schema.

Group Synchronization:
GitLab Premium and Ultimate support LDAP group syncing—mapping LDAP groups to GitLab groups with access levels and ongoing membership syncs. This is not available in free/Community tiers; group restriction by filter is still possible everywhere.

Testing Your LDAP Integration

Pre-rollout validation is critical—misconfiguration can lock out all users, including administrators. Test with:

bash
sudo gitlab-rake gitlab:ldap:check

This command checks:

  • Connection to the LDAP server (including network, port, encryption)
  • Bind credentials for bind_dn
  • Ability to search for and list LDAP users based on the current config

Review the output carefully:

  • Pass: Configuration is likely correct—review sample users shown.
  • Fail: Inspect errors indicating why connection, authentication, or search failed.

Testing group restriction: Attempt login with test accounts both inside and outside the group targeted by your user_filter (never test with your only admin account).

Troubleshooting: Diagnosing and Resolving Common LDAP Issues

Common integration problems include:

  • Connection Refused: Network problems, wrong port, firewall, or LDAP service offline.
  • Invalid Credentials: Incorrect bind_dn or password, expired account, or insufficient directory permissions.
  • Configuration/Indentation Errors: YAML syntax mistakes or misplaced keys in gitlab.rb silently prevent correct LDAP parsing. Always check for tabs or off-by-one indentation.
  • No Users Returned: Misconfigured base DN or overly restrictive user_filter. If too broad, unwanted users may gain access; too narrow may miss valid users.
  • Group Sync Failures: Attribute mapping errors or insufficient permissions for group lookup. Make sure the service account can read group memberships.

Use gitlab:ldap:check for diagnosis; for advanced troubleshooting, external tools like ldapsearch can further confirm directory structure and filter queries.

Security Considerations and Attribute Risks

LDAP integration introduces several non-obvious security risks:

  • Attribute Mutability: If users can modify their unique identifying LDAP attributes, especially mail or userPrincipalName, they could hijack or link to unintended GitLab accounts.
  • Non-Unique Emails: Multiple LDAP users sharing email addresses can result in account overlaps or unauthorized access.
  • User Takeover: Changing a user’s email attribute after initial account creation may disconnect or connect GitLab accounts incorrectly.
  • Bind Account Scope: The LDAP bind user should have the minimum necessary search permissions and never be reused for unrelated administrative activities.

Best practices:

  • Ensure all identifiers used for mapping (email, UID) are unique and immutable in LDAP.
  • Restrict directory attributes from being user-changeable for authentication-critical fields.
  • Consider using group filters to precisely restrict access, especially in directories with broad ACLs.

Best Practices for Reliable GitLab LDAP Integration

To maintain a secure and reliable setup:

  • Test All Changes: Always use gitlab:ldap:check and non-admin test users before deploying configuration updates.
  • Backup Configuration: Version-control your gitlab.rb with access controls. Document all changes and rationale.
  • Operational Reviews: Regularly confirm directory schema, filter scopes, and user mappings to detect drift or misconfigurations.
  • Monitor Synchronization: Automate monitoring for ldap_blocked statuses, group sync mismatches, and failed login attempts.
  • Change Management: Notify users ahead of planned authentication attribute changes, and coordinate with the directory admin before schema or group changes.
  • Security Reviews: Periodically audit accessible attributes, directory permissions, and unique identifier policies.

With careful configuration, routine validation, and attention to attribute and access security, LDAP integration for GitLab can deliver strong, maintainable identity management that aligns with both GitLab and organizational policy.

Sources

Related resources