Diagnosing GitLab LDAP Authentication Failures (v13‑16)

Problem Statement

When users try to log in through LDAP, GitLab may return “LDAP authentication failed” or similar errors. The failure can stem from host resolution, bind credentials, TLS trust, filter settings, or network blocks. This guide walks through a systematic diagnostic flow to pinpoint the root cause and apply the correct fix.

Quick Diagnostic Table

Condition	Likely Cause	Diagnostic Check	Fix
No users appear in GitLab after LDAP sync	Base DN or filter mis‑configured	Review gitlab_rails['ldap_servers'] block	Correct base or user_filter
Connection timeout to LDAP host	Hostname unresolved or port blocked	Ping/resolve host, telnet to port	Update host or open firewall rule
Bind DN errors (e.g., “Invalid credentials”)	Wrong bind DN or password, or account expired	Test bind with ldapsearch	Reset password or correct DN
SSL/TLS errors (“certificate unknown”)	Server certificate not trusted	Validate CA chain on GitLab host	Install CA cert or set verify_cert to false (not recommended)
LDAP sync runs but no users are added	Filter excludes all entries	Run ldapsearch with the filter	Adjust filter expression

Step‑by‑Step Diagnostics

1. Verify Hostname and Port Accessibility

   Run from the GitLab host:

   # Resolve the LDAP host
   nslookup ldap.example.com
   # Test TCP connectivity
   nc -vz ldap.example.com 636
   

   Expected: host resolves, port 636 (or 389) responds. If the command fails, check DNS, hosts file, or firewall.

2. Test Bind DN Credentials

   Use ldapsearch to bind with the configured DN and password:

   ldapsearch -x -H ldaps://ldap.example.com:636 \
     -D "CN=gitlab,OU=Service Accounts,DC=example,DC=com" \
     -w PASSWORD_PLACEHOLDER \
     -b "DC=example,DC=com" \
     '(objectClass=person)' | head
   

   Replace PASSWORD_PLACEHOLDER with the actual password. A successful bind returns entries; “invalid credentials” indicates a mismatch or expired account. If the bind fails, reset the service account password and update gitlab_rails['ldap_servers']['main']['password'].

3. Check TLS/SSL Trust

   If using LDAPS, ensure GitLab trusts the LDAP server’s certificate:

   # Verify the server cert chain
   openssl s_client -connect ldap.example.com:636 -showcerts
   

   Copy the server’s cert and install it in /etc/ssl/certs/ or the Java trust store if GitLab runs in a container. Alternatively, set verify_cert: false for quick testing (not for production).

4. Validate LDAP Filters

   Run a search that matches the filter used in GitLab:

   ldapsearch -x -H ldaps://ldap.example.com:636 \
     -D "CN=gitlab,OU=Service Accounts,DC=example,DC=com" \
     -w PASSWORD_PLACEHOLDER \
     -b "DC=example,DC=com" \
     '(objectClass=person)' | wc -l
   

   Compare the count with the expected number of users. If zero, adjust user_filter (e.g., remove attribute restrictions).

5. Inspect Network/Firewall Rules

   From the GitLab host, confirm that outbound traffic to the LDAP port is allowed:

   # On Linux with iptables
   iptables -L -n | grep 636
   # On firewalld
   firewall-cmd --list-all
   

   Open the port if blocked.

Applying Fixes

• Update gitlab.yml (Omnibus) or gitlab.rb (Omnibus) with corrected values.
• For self‑hosted GitLab, edit config/gitlab.yml directly.
• After any change, restart GitLab to apply the new LDAP configuration:

  # Omnibus
  sudo gitlab-ctl restart
  # Source‑installed
  sudo systemctl restart gitlab
  

• Run the built‑in test button in the GitLab Admin Area (Admin > LDAP) or use the command:

  gitlab-rails runner 'Gitlab::LDAP::Adapter.new(:main).test_connection'
  

• Check logs for bind or search errors:

  sudo gitlab-ctl tail gitlab-workhorse | grep LDAP
  

Post‑Fix Verification

After restarting, attempt a user login via LDAP. In the Admin Area, the Last LDAP sync timestamp should update. Use gitlab-rake gitlab:ldap:check (for older GitLab) or run a manual sync with gitlab-rails runner 'Gitlab::LDAP::Sync.new.sync' to confirm users appear.

Escalation Criteria

1. All diagnostic checks pass, but users still cannot authenticate.
2. LDAP server logs show successful binds but GitLab receives no entries.
3. After a recent GitLab upgrade (v15+), TLS errors appear even with a valid CA.

In these cases, contact your LDAP administrator to verify schema compatibility and ensure the service account has the necessary permissions. If the problem persists, open a support ticket with GitLab, providing logs and the results of the diagnostics above.

Summary

LDAP authentication failures in GitLab are almost always caused by configuration mismatches or network blocks. By following the diagnostic table and ordered checks, you can quickly isolate the issue and apply the correct fix. Remember to restart GitLab after any configuration change and verify the result with the built‑in test or a manual sync.