Introduction

LDAP integration allows Grafana to authenticate users against corporate directories like Active Directory or OpenLDAP. When LDAP authentication fails, users cannot log in despite having valid credentials in the directory. The error usually appears as "Login failed" in the UI, while the backend logs contain more specific details about bind failures, search errors, or TLS issues.

Symptoms

  • Users cannot log in with valid LDAP credentials
  • Error in Grafana logs: "LDAP bind failed" or "LDAP search error"
  • Error: "failed to authenticate user" with LDAP backend
  • Some users can authenticate while others cannot (group membership issues)
  • Error: "certificate verify failed" or "TLS handshake error"
  • Login works for admin users but not for LDAP users

Common Causes

  • LDAP server address or port is incorrect
  • Bind DN or bind password is wrong or expired
  • TLS/SSL certificate verification fails
  • User search filter does not match directory structure
  • Group membership attribute mapping is incorrect
  • LDAP server firewall rules block Grafana's IP
  • LDAP server requires StartTLS but Grafana uses plain connection

Step-by-Step Fix

Test LDAP Connectivity

  1. 1.Verify basic connectivity to LDAP server:
  2. 2.```bash
  3. 3.# Test TCP connectivity
  4. 4.nc -zv ldap.example.com 389
  5. 5.nc -zv ldap.example.com 636

# Test with ldapsearch ldapsearch -x -H ldap://ldap.example.com:389 -b "dc=example,dc=com" "(objectClass=*)" dn ```

  1. 1.Test LDAPS (SSL) connectivity:
  2. 2.```bash
  3. 3.ldapsearch -x -H ldaps://ldap.example.com:636 -b "dc=example,dc=com" "(objectClass=*)" dn
  4. 4.`

Fix Bind Configuration

  1. 1.Verify bind credentials can authenticate:
  2. 2.```bash
  3. 3.# Test bind with configured credentials
  4. 4.ldapsearch -x -H ldap://ldap.example.com:389 \
  5. 5.-D "cn=grafana,ou=service-accounts,dc=example,dc=com" \
  6. 6.-W \
  7. 7.-b "dc=example,dc=com" \
  8. 8."(objectClass=user)" sAMAccountName
  9. 9.`
  10. 10.Check the LDAP configuration in /etc/grafana/ldap.toml:
  11. 11.```toml
  12. 12.[[servers]]
  13. 13.host = "ldap.example.com"
  14. 14.port = 389
  15. 15.use_ssl = false
  16. 16.start_tls = true
  17. 17.ssl_skip_verify = false

bind_dn = "cn=grafana,ou=service-accounts,dc=example,dc=com" bind_password = "your-bind-password"

# User search configuration search_filter = "(sAMAccountName=%s)" search_base_dns = ["ou=users,dc=example,dc=com"] ```

Fix User Search Configuration

  1. 1.Test user search filter matches your directory structure:
  2. 2.```bash
  3. 3.# For Active Directory
  4. 4.ldapsearch -x -H ldap://ldap.example.com:389 \
  5. 5.-D "cn=grafana,ou=service-accounts,dc=example,dc=com" \
  6. 6.-w "password" \
  7. 7.-b "ou=users,dc=example,dc=com" \
  8. 8."(sAMAccountName=johndoe)" dn sAMAccountName mail

# For OpenLDAP ldapsearch -x -H ldap://ldap.example.com:389 \ -D "cn=admin,dc=example,dc=com" \ -W \ -b "ou=people,dc=example,dc=com" \ "(uid=johndoe)" dn uid mail ```

  1. 1.Update search filter for your directory type:
  2. 2.```toml
  3. 3.# Active Directory
  4. 4.search_filter = "(sAMAccountName=%s)"

# OpenLDAP search_filter = "(uid=%s)"

# Generic LDAP search_filter = "(cn=%s)" ```

Fix TLS/SSL Issues

  1. 1.For certificate verification errors, either fix the trust chain or temporarily disable verification:
  2. 2.```toml
  3. 3.# In ldap.toml - Option 1: Add CA certificate
  4. 4.[[servers]]
  5. 5.host = "ldap.example.com"
  6. 6.port = 636
  7. 7.use_ssl = true
  8. 8.ssl_skip_verify = false
  9. 9.root_ca_cert = "/etc/ssl/certs/ldap-ca.crt"

# Option 2: Skip verification (not recommended for production) ssl_skip_verify = true ```

  1. 1.For StartTLS configuration:
  2. 2.```toml
  3. 3.[[servers]]
  4. 4.host = "ldap.example.com"
  5. 5.port = 389
  6. 6.use_ssl = false
  7. 7.start_tls = true
  8. 8.ssl_skip_verify = false
  9. 9.`

Fix Group Mapping

  1. 1.Verify group membership attribute mapping:
  2. 2.```bash
  3. 3.ldapsearch -x -H ldap://ldap.example.com:389 \
  4. 4.-D "cn=grafana,ou=service-accounts,dc=example,dc=com" \
  5. 5.-W \
  6. 6.-b "dc=example,dc=com" \
  7. 7."(sAMAccountName=johndoe)" memberOf
  8. 8.`
  9. 9.Configure group mapping in ldap.toml:
  10. 10.```toml
  11. 11.[[servers.group_mappings]]
  12. 12.group_dn = "cn=grafana-admins,ou=groups,dc=example,dc=com"
  13. 13.org_role = "Admin"

[[servers.group_mappings]] group_dn = "cn=grafana-editors,ou=groups,dc=example,dc=com" org_role = "Editor"

[[servers.group_mappings]] group_dn = "*" org_role = "Viewer" ```

Enable Debug Logging

  1. 1.Enable LDAP debug logging for detailed errors:
  2. 2.```ini
  3. 3.# In grafana.ini
  4. 4.[log]
  5. 5.level = debug

[log.filters] ldap = debug ```

  1. 1.Check debug logs for authentication attempts:
  2. 2.```bash
  3. 3.journalctl -u grafana-server -f | grep -i ldap
  4. 4.`

Verification

  1. 1.Test LDAP authentication with debug mode:
  2. 2.```bash
  3. 3.grafana-cli admin data-migration ldap-sync
  4. 4.`
  5. 5.Log in as an LDAP user and verify:
  6. 6.- User appears in Configuration > Users
  7. 7.- User has correct organization role
  8. 8.- User can access appropriate dashboards
  9. 9.Check logs for successful LDAP authentication entries.