Connect Grafana to LDAP

Connect Grafana to LDAP, configure secure server settings and group mappings, test directory queries, and diagnose login or role problems.

Type
Tutorial
Level
Intermediate
Technologies
LDAP, LDAPS
On this page

Connecting LDAP to Grafana lets you centralize user authentication and control access with your enterprise directory. This integration allows developers and identity engineers to align dashboard permissions and roles in Grafana with the authoritative structure of systems like Active Directory or OpenLDAP. This guide explains the setup process, security decisions, mapping strategies, and real-world troubleshooting techniques using both file-based and UI-based workflows.

Why Connect LDAP to Grafana?

LDAP integration enables Grafana to:

  • Authenticate users using your directory’s records (not just local accounts).
  • Map group memberships or organizational units in LDAP to specific Grafana roles.
  • Automate user lifecycle management—provisioning, deprovisioning, and access right changes—all following directory policies.

Use LDAP-backed authentication when you want centralized user management, automatic group-to-role privileges, and stricter lifecycle control, as opposed to manual local account management.

LDAP Integration Prerequisites

Before integrating LDAP with Grafana, you’ll need:

  • Directory type and connection details: Know your LDAP server addresses, port(s), and schema layout. Both Active Directory, OpenLDAP, and other LDAPv3-compliant servers are supported.
  • Bind account information: Typically, a non-privileged LDAP "bind" account is used so Grafana can search for users and groups. This account should have read-only access over the relevant OUs. Note: A bind_password is not always mandatory—certain directory types like Active Directory can be configured for user bind (for example, by making bind_dn = 'DOMAIN\\%s'), or even, in rare cases, anonymous binding. However, anonymous or unauthenticated binds are discouraged due to security risks and lack of auditability. Always prefer a dedicated, least-privilege, credentialed bind user unless you have reviewed your directory’s security implications.
  • Directory structure awareness: Determine user and group base DNs and suitable search filters (e.g., CN=Users,DC=example,DC=com).
  • Login attribute knowledge: Know which unique attribute (username, email, or custom field) your users employ to log in; this sharpens your search_filter.
  • Firewall/network readiness: Ensure Grafana can access the LDAP server securely (ports 389 for LDAP/StartTLS, 636 for LDAPS).

Connecting Grafana to LDAP: File-Based and UI Approaches

Grafana supports two integration models for LDAP:

File-Based Configuration (ldap.toml)

  • Where: The ldap.toml file resides in Grafana’s configuration directory.
  • Appropriate for: Automated environments, source-controlled deployments, scenarios with complex or multiple directory integrations.
  • Features: Every LDAP option is configurable; supports several directories/domains using multiple [[servers]] blocks.
  • Persistence: Durable across upgrades if managed via automation.

UI-Based Configuration

  • Where: Available in Grafana Enterprise and Grafana Cloud editions.
  • Appropriate for: Teams preferring graphical configuration or initial setup without direct file edits.
  • Features: Walks you through most required LDAP fields via forms. Advanced options or support for multiple directories may still require manual edits in ldap.toml.
  • Persistence: Settings live in Grafana’s database, update instantly, but should be exported for disaster recovery documentation.

How to choose: Both approaches control the same underlying mechanisms. Prefer ldap.toml when versioning or complex mapping is needed; use the UI for simplicity or less technical administration.

LDAP Connection Security: LDAPS, StartTLS, and Certificates

Protect all credentials and user data as they traverse the network between Grafana and your LDAP server:

LDAPS and StartTLS: Key Distinctions and Security

  • LDAPS: Runs LDAP directly over SSL/TLS (typically port 636). The connection is encrypted from the outset.
  • StartTLS: Begins as plaintext on standard LDAP port 389, then upgrades to secure TLS with a StartTLS command after connection.

Warning: LDAPS and StartTLS are not identical or fully interchangeable. They use different negotiation methods, require different ports, and may vary in certificate handling at the server or firewall level. Do not assume a configuration for one will automatically work with the other.

  • Always prefer encrypted connections in production—never use plaintext LDAP for sensitive authentication.
  • In configuration, use use_ssl = true for LDAPS or start_tls = true for StartTLS, and ensure the correct port is in use (636 or 389, respectively).
  • Certificate handling: Never disable SSL verification (ssl_skip_verify = true) in production. This setting skips validation of the LDAP server's certificate and exposes login credentials to potential interception or man-in-the-middle attacks. If your environment uses a custom or private CA, specify root_ca_cert to establish trust.

Development shortcuts—like using insecure connections or disabling certificate checks—must not be carried into deployed environments.

Key Configuration Parameters Explained

Thorough understanding of ldap.toml (or the UI's fields) is critical:

Example — Connection and Search Basics

toml
[[servers]]
host = "ad.example.com"
port = 636
use_ssl = true
bind_dn = "CN=readonly,CN=Users,DC=example,DC=com"
bind_password = "ENV_VAR_GRAFANA_LDAP_PASSWORD"
search_base_dns = ["CN=Users,DC=example,DC=com"]
search_filter = "(sAMAccountName=%s)"

[servers.attributes]
name = "givenName"
surname = "sn"
username = "sAMAccountName"
email =  "mail"
  • host/port: Target LDAP server and port (636 for LDAPS, 389 for StartTLS).
  • use_ssl / start_tls: Boolean flags for connection security (never both true).
  • bind_dn / bind_password: Credentials for the directory bind user (may reference environment variables for security).
  • search_base_dns: Array of DNs to initiate search—for example, where users reside.
  • search_filter: The LDAP search pattern; %s is replaced with the login value entered in Grafana.

Group Mapping

User mapping (locating and authenticating who a user is) and group mapping (assigning roles or teams based on groups) are distinct steps. Correct configuration requires attention to both processes.

Example — Complete [[servers.group_mappings]] Block

toml
[[servers.group_mappings]]
group_dn = "CN=GrafanaAdmins,OU=Groups,DC=example,DC=com"
org_role = "Admin"

[[servers.group_mappings]]
group_dn = "CN=GrafanaEditors,OU=Groups,DC=example,DC=com"
org_role = "Editor"

[[servers.group_mappings]]
group_dn = "*"
org_role = "Viewer"
  • The first matching group_dn assigns the role; mappings are prioritized in order.
  • You may define multiple mapped groups for tiered permissions.
  • For directories lacking the memberOf attribute, use group_search_filter and configure searches by user membership.

Multiple Directory Support

Grafana allows several [[servers]] blocks inside ldap.toml, so you can enable login from multiple independent directories or domains within a single Grafana deployment.

User and Group Mapping Strategies

User Search Filters

Adjust search_filter to match how users identify themselves:

  • Username (Active Directory): (sAMAccountName=%s)
  • Username (OpenLDAP): (uid=%s)
  • Support login via email or username: (|(sAMAccountName=%s)(mail=%s))
  • Non-standard schemas: Adjust filter to target your user attribute (e.g., (customAttribute=%s)).

Tip: Use %s in the filter—Grafana replaces it with the user's login value.

Group Mapping Methods

  • Direct mapping: Reference the exact group DN. For example, group_dn = "CN=GrafanaEditors,OU=Groups,DC=example,DC=com".
  • Team/role sync: Use multiple group mappings to assign various roles; mapping order decides which role applies.
  • Non-standard group structures: If your directory doesn't populate memberOf, specify group_search_filter and group search attributes directly.

Best practices:

  • Structure directory groups to match Grafana team needs precisely.
  • Avoid wildcard group searches unless necessary—this prevents unauthorized privilege escalation.

Testing and Troubleshooting LDAP Authentication

Enabling Debug Logging

Adjust grafana.ini:

toml
[log]
filters = ldap:debug

This will output verbose LDAP operations—connection, bind, search, and mapping attempts—to the Grafana logs.

Validating Directory Connectivity

Tools like ldapsearch help confirm connection and filter correctness outside of Grafana. For example:

bash
ldapsearch -H ldaps://ad.example.com:636 -D "CN=readonly,CN=Users,DC=example,DC=com" -W -b "CN=Users,DC=example,DC=com" "(sAMAccountName=jdoe)"
  • Replace values as required for your directory and SSL/TLS needs.
  • If results are empty or you get errors, check your credentials, ports, and search base/filter before troubleshooting Grafana.

Common Issues and Resolutions

  • Cannot connect to LDAP: Check network reachability and ensure SSL/TLS is correctly configured; watch for certificate errors.
  • Bind failures: Verify bind_dn and password (test directly with ldapsearch or similar tools).
  • User not found: Re-examine search_base_dns and search_filter—test queries with directory tools.
  • Incorrect group mapping: Check syntax of group_dn and the existence of memberOf; validate group searches as needed.
  • Unexpected role assignments: Remember, only the first matching group_mapping applies; check mapping order and filters.

Careful inspection of Grafana logs with debug enabled will indicate the failure phase: connection, bind, user search, group mapping, or attribute extraction.

Security Best Practices and Maintenance Tips

  • Least-privilege binds: Ensure the bind user can only read necessary user and group OUs.
  • Secret management: Use environment variables for bind_password and rotate credentials periodically. Never hard-code sensitive credentials in deployment files.
  • Certificate validation: Do not skip SSL or TLS verification in production environments.
  • Monitoring/audit: Review authentication logs for failed login attempts or unusual patterns. Integrate with your organization's monitoring to alert on suspicious activity.

Regularly review LDAP and Grafana configurations, especially when directory membership or structure changes.

LDAP Authentication vs Other Methods in Grafana

Grafana’s authentication options include:

  • LDAP: Tightly binds access and roles to your directory structure. Best when granular group-to-role control is needed and direct SSO is not available.
  • SSO (SAML/OAuth): Supports full single sign-on across SaaS/cloud applications, usually more seamless for end-users.
  • Hybrid: You may enable both LDAP and other authentication providers in parallel, and, with multiple [[servers]] blocks, Grafana can authenticate users from several domains or directories in the same instance.

LDAP is preferable for highly controlled environments where group and role mapping must mirror your directory with precision and when SSO isn't required or available.

References and Further Reading

  • Canonical ldap.toml example (all supported options and syntax): github.com/grafana/grafana/blob/main/conf/ldap.toml
  • Comprehensive discussion on directory account and password requirements for AD: github.com/grafana/grafana/issues/10040
  • LDAP protocol specification (RFC 4511): docs.ldap.com/ldap-sdk/docs/specs/rfc4511.txt

Sources

Related resources