Grafana LDAP and Active Directory authentication

Configure self-hosted Grafana to sign users in against LDAP or Active Directory with ldap.toml, mapped group roles and verified TLS. Covers bind design, nested groups and debugging.

On this page

How Grafana LDAP authentication signs Active Directory users in

If your team runs self-hosted Grafana and must sign in people from an existing Active Directory domain, Grafana's built-in LDAP support is the direct path when Entra ID or SAML is not in use. It is configured through ldap.toml, and according to the Grafana authentication docs, LDAP is available in every edition, so you do not need an Enterprise license to sign users in against your directory. The trade-off is that you own the directory connection, its certificates and its failure modes, which an identity provider in front of Grafana would otherwise absorb.

At login, Grafana does not authenticate the user against a fixed account. It first uses a service account, or the anonymous bind your directory allows, to search for the user's entry under the configured base DN and filter. It then attempts a bind as that user with the password they entered, which is the check that actually proves identity. Once the bind succeeds, Grafana reads the user's attributes and group memberships and maps them to an organization and role. Confirm with your directory team which attributes and group objects your Active Directory exposes, because the mapping only works on what the search returns. Note that team sync, which keeps Grafana teams aligned with directory groups, is an Enterprise feature, so an open-source LDAP setup maps groups to roles but does not manage teams for you.

Plan for the boundary early. Ask whether your security policy requires Grafana to be the only place where directory groups become Grafana permissions, and if so, check with your Grafana edition and licensing terms before you design around team sync. Confirm the exact supported behavior for your Grafana version in the Grafana authentication docs before you commit to an architecture.

What the directory, Grafana and network need before configuration

LDAP sign-in for Grafana depends on three things lining up: the Active Directory structure Grafana will query, the Grafana release and database it runs on, and the network path and certificates that carry the bind and search traffic. Settling these before editing ldap.toml avoids most failed logins that look like configuration errors.

Domain controllers and reachable endpoints

Grafana talks to Active Directory over LDAP, so it needs a stable name and network path to the domain controllers, not a single server. Confirm which domain controllers are reachable from the Grafana hosts, which ports your firewall allows, and whether you will point at a load-balanced name or specific controllers. Microsoft's directory overview describes AD DS as replicating directory data to every domain controller in a domain, so any controller should answer for your users, but you must confirm that replication is healthy before you rely on it.

Bind account with read access

Decide between a dedicated bind account and a single bind, where Grafana authenticates each user with that user's own credentials. A low-privilege service account with read access to the user and group containers is the usual choice for search-then-bind flows. Ask the directory team to confirm the account can read the attributes you map, such as mail, memberOf and the login name, and that its password follows a rotation process your team can support.

Directory objects and group structure

Map the containers that hold users, the attribute that carries the login name in your domain, and the groups you intend to map to Grafana organization roles. Note whether groups are nested, because membership resolved through nested groups is not always visible to a simple memberOf lookup. Write down which group names will map to Viewer, Editor and Admin roles and which organizations they belong to, so the search filter and mappings can be tested against real accounts.

Grafana release and database choice

Confirm the Grafana release you will target on the releases page, then verify each ldap.toml option against the authentication docs for that exact version. For production and high availability, Grafana's installation docs require MySQL 8.0 or later or PostgreSQL 12 or later, because SQLite does not scale for production. Users, sessions and LDAP-synced organization memberships live in that database, so plan for backups and a database that every Grafana node can reach.

LDAP over TLS and certificates

Credentials sent over plain LDAP are exposed on the wire, so plan LDAP over TLS (LDAPS) or StartTLS from the start. Obtain the certificate chain for the domain controllers, confirm that the Grafana hosts trust the issuing certificate authority, and check that the certificate name matches the host name you configure. Test the chain with the same host and port Grafana will use before you change the configuration, since certificate errors are a common cause of login failures.

Firewall and name resolution

Every Grafana node that will authenticate users needs a route to each LDAP endpoint on the agreed port, and each must resolve the domain controller names correctly. In high availability deployments, Grafana runs as two or more active-active servers behind a load balancer, so check the path from every node, not only the first one. Ask your network team to confirm the rules in writing, and record the source addresses so a later firewall review can trace them.

Bind account or single bind: choosing the search and bind pattern

With a bind account, Grafana first connects to the directory using a dedicated service identity, searches for the user by a filter such as the sAMAccountName, and then attempts a second bind as the distinguished name it found. With a single bind, Grafana builds the user's distinguished name from a template and binds directly as that user, so no search account is needed. The first pattern handles users whose location in the directory is unpredictable. The second is simpler but assumes every user sits in one predictable place.

  • Search then bind: Grafana uses a service identity to locate the entry, which tolerates users spread across organizational units.
  • Direct bind: Grafana constructs the distinguished name itself, so there is one less account to manage.
  • Lookup cost: The search pattern adds a directory query to every login.
  • Predictability: The single bind only works when the naming and placement of user objects is consistent.
  • Option names: Confirm the exact bind and search keys in the Grafana authentication docs for your version before writing ldap.toml.

Before you choose, check with your directory team whether user objects follow one naming scheme across every domain controller and organizational unit.

Configuring ldap.toml step by step with a check at each stage

This sequence takes a self-hosted Grafana instance from a disabled LDAP setting to verified group-to-role assignments for Active Directory users. Each stage ends with a check, so a fault is found while the configuration is still small and easy to reverse.

  1. Prepare a least-privilege bind account

    Your directory team creates a dedicated service account in Active Directory that Grafana uses to search for users. It should have read access to the user objects and group membership under the search base, and no interactive logon or administrative rights. Record its distinguished name and password in your secrets store, not in a shared document. The check is a successful manual bind from a host that can reach your domain controllers, performed with a standard LDAP client, before Grafana is involved at all.

  2. Enable LDAP in the Grafana configuration

    On the Grafana server, the administrator sets the LDAP switch in the main configuration file, usually grafana.ini, under the [auth.ldap] section, and points config_file at the path of your ldap.toml. Keep the file readable only by the Grafana service user because it will hold the bind password. Restart Grafana after the change. The check is that the Grafana log shows LDAP initialized without a configuration error, and the login page still accepts your existing local admin account, so you keep a way back in.

  3. Write ldap.toml with server, search base and filter

    Create ldap.toml with the host and port of your domain controllers, the search base for the organizational unit that holds your users, and a user search filter that matches the sAMAccountName attribute your staff log in with. Name the attributes Grafana reads for login, name, surname and email, since the email attribute is required. Use a domain controller name that matches its certificate, because name mismatches are a common cause of TLS failures later. The check is a configuration validation run, and then a connection test that returns the expected user entry for one known account.

  4. Choose and configure the bind pattern

    Decide between a bind account and a single bind. With a bind account, Grafana first binds as the service account, searches for the user, and then binds again as that user to verify the password. With a single bind pattern, the user's own credentials are used directly against a distinguished name template, which removes the service account but requires that the name format be predictable. Test the pattern you chose against one account. The check is a log line confirming the bind succeeded for that user, and a failed attempt with a wrong password producing a clear authentication error rather than a silent login.

  5. Add TLS settings with a trusted CA

    Configure the TLS settings so Grafana connects to the domain controllers over LDAPS or StartTLS, with certificate verification enabled. Point Grafana at the root or intermediate CA certificate that issued your domain controller certificates, and confirm the certificate is valid for the host name in your configuration. Avoid disabling certificate verification to make an error go away, because that exposes bind passwords to interception. Confirm which port and protocol your directory accepts with your directory team. The check is a repeated test login for the known user, now over the encrypted connection, with no certificate warnings in the Grafana log.

  6. Test a single known user end to end

    Before mapping any groups, sign in to Grafana with one known Active Directory account that belongs to a group you expect to use. Use a second browser session or a private window so the admin session stays intact. Confirm that the user is created in Grafana with the expected name and email, and that the sign-in lands on a home page. If the login fails, enable LDAP debug logging temporarily, reproduce the attempt once, and read the lines that show the search result and the bind outcome. The check is a successful login recorded in the user list, with the correct identity fields.

  7. Map groups to org roles and verify assignment

    Add group mappings in the [[servers.group_mappings]] sections of ldap.toml, matching each Active Directory group's distinguished name to an organization and a Grafana role such as Viewer, Editor or Admin. Confirm that your directory returns the group membership attributes Grafana reads, and decide how nested groups will be handled, since membership through a nested group must be resolved by the search. Sign in again with the test user and check the role on the organization page. The check is that the role shown matches the group membership, and that a user in no mapped group is denied or given the default role you set.

Mapping Active Directory attributes and groups to Grafana roles and orgs

This table compares how each part of an Active Directory identity maps into Grafana's ldap.toml settings, from login and email fields through group entries to the server admin flag. Read each row against your own directory schema, since attribute names vary by domain and the group DN must match exactly what the directory returns. The main takeaway is that a user who matches no mapped group still needs an explicit decision about whether they can sign in at all.

ItemWhat to configureWhat to confirm before go-live
Login attributeMap the directory attribute that users type at sign-in, typically sAMAccountName or userPrincipalName, to Grafana's login fieldConfirm which form your users expect and that it is unique across every domain you search
Email attributeMap the mail attribute to Grafana's email field, since Grafana needs an email value for each userConfirm that every account in scope populates mail, including service and shared mailboxes you may want excluded
Display name attributeMap displayName to Grafana's name field so audit entries and user lists are readableConfirm the attribute is populated for contractors and accounts created by provisioning scripts
Group DN matchingEach group_search_filter or group mapping entry must reference the full distinguished name of the AD security groupConfirm the exact DN with your directory team, since a single character or casing difference will prevent a match
Organization and role entriesEach group entry is paired with an org_id and a Grafana role such as Viewer, Editor or AdminConfirm that each role grant reflects a documented access decision and that group membership is controlled by your identity team
Users in no mapped groupGrafana denies or limits access depending on the configuration, so a user with no matching group needs an explicit outcomeTest a sign-in with an account in no mapped group and confirm the result matches your access policy
Server admin flagServer admin rights are granted through a separate group entry, and this should be restricted to a small platform team groupConfirm that the admin group is reviewed on the same cadence as privileged directory groups and that no broad group is mapped to it
Nested groupsNested membership depends on how the directory answers group queries, so confirm whether the search returns indirect membersTest a user who is only a member of a child group and confirm the expected role is applied

Handling nested groups and multiple domains

Nested group membership is the part of an Active Directory LDAP setup most likely to produce silent role errors. A user who belongs to a group that is itself a member of the group Grafana checks may log in with the wrong role or none at all, because the group filter in ldap.toml only sees the memberships the directory returns for that user. Before you write any group_search_filter or group_mappings entry, decide which membership Grafana must evaluate: direct membership only, or the transitive closure that Active Directory resolves through the LDAP_MATCHING_RULE_IN_CHAIN matching rule. Then confirm with a test user that the groups returned match what you expect. Nested groups also multiply the number of groups per user, so keep the mapping list short and map each role from a single, deliberately chosen group.

Multiple domains and forests change three settings: the search_base_dns, the placement of the bind account, and the host list. Each domain has its own naming context, so a search base scoped to one domain will never return users from another. The bind account must have read access in every domain whose users you intend to authenticate, and a bind account in one domain will often fail to resolve referrals into a different one. If you point host at domain controllers across several domains, verify that each server answers for the naming context you expect. Trust relationships between domains and forests determine whether referrals are followed at all, so confirm the trust direction, selective authentication settings and referral behavior with your Active Directory administrators rather than assuming they match the design document.

Run per-domain testing before go-live. Use a test account from each domain and each forest, including a user who is a member only through a nested group and a user whose group sits in a trusted domain. For each account, record the login result, the role Grafana assigns and the group list seen in the debug log, and repeat the test after any change to trusts, bind permissions or domain controller addresses. Ask your directory team to document which domain controllers Grafana will reach and whether they are global catalog servers, because that affects which attributes are searchable. Treat a passing test in one domain as evidence for that domain only.

TLS, bind credentials and access controls that matter

The LDAP connection carries credentials and directory data between Grafana and your domain controllers, so its transport, bind account and network reach need the same scrutiny as the login page itself. The cards below cover the controls that protect that path and the Grafana settings that protect the sessions it creates.

Encrypt the directory connection

Use LDAP over TLS (port 636) or StartTLS so simple bind credentials never cross the network in clear text. Point Grafana at the certificate chain of your internal CA and keep certificate validation on, since disabling it removes the protection TLS provides. Confirm the exact option names for TLS mode, CA path and certificate verification in the Grafana configuration docs for your version before you change anything in production.

Protect the bind password

Store the bind account password in a secret source, not in a plain value committed to version control or a shared configuration file. Restrict read access to ldap.toml on the host to the Grafana service account and administrators. Plan a rotation procedure that updates the password in Grafana and in the directory at the same time, so a rotation does not lock out every user at once.

Give the bind account least privilege

Create a dedicated service account in Active Directory that can read only the user and group attributes Grafana needs, such as the login name, mail address and member-of values. Do not place it in Domain Admins or any group with write rights. Ask your directory team to document which OUs the account can read so access reviews can confirm the scope.

Restrict network reach to the directory

Allow only the Grafana servers to open connections to the domain controllers on the LDAP and LDAPS ports, and block that path from user networks. In a high availability deployment, every Grafana node needs the same reach, so include each node in the firewall rule set. Verify the path with a test connection from each node rather than assuming the rule is in effect.

Refuse anonymous binds

Anonymous binds let unauthenticated clients query the directory, and they can expose user names and group structure to anyone who reaches the port. Confirm that the directory allows anonymous queries only where a documented need exists, and that Grafana authenticates with the named bind account. Test that a failed bind produces a login failure, not a silent fallback to anonymous access.

Harden Grafana sessions and keep a break-glass admin

Enable secure cookies and SameSite cookie settings in the Grafana server configuration, as the security hardening guidance recommends, so LDAP-issued sessions resist cookie theft and cross-site requests. Keep the local admin account enabled and its password stored offline, so administrators can still sign in if the LDAP connection, certificate or bind account fails.

Why Active Directory logins fail and how to isolate the cause

This table maps common Active Directory login failures in self-hosted Grafana to their likely cause and fix. Start from the symptom a user or administrator sees, then use LDAP debug logging to confirm which lookup or bind step fails before changing configuration. Remove debug logging once the cause is confirmed.

SymptomLikely causeFix and how to confirm
Login fails with a TLS or certificate validation error in the Grafana logThe domain controller certificate is not trusted by the Grafana host, or the hostname does not match the certificateInstall the issuing CA certificate on the Grafana host, connect using the name on the certificate, and confirm the chain with an LDAP client from the same host
Login is rejected and debug output shows zero entries from the searchWrong search base or search filter, for example a base DN for the wrong domain or a filter that does not match the login attributeCorrect the search_base_dns and search_filter in ldap.toml, then test the filter against the directory with an LDAP client using the same bind account
Bind fails with invalid credentials or the account is reported as lockedBind account password expired, account locked after repeated failures, or the account lacks read rights to the user and group objectsUnlock or reset the bind account, confirm it can read the user subtree, and grant read access to the required OUs without giving it write rights
User authenticates but receives no role or is deniedThe user is not a member of a group listed in group_search_base_dns or in the group_mappings entries, or nested membership is not resolvedCheck the user's group memberships in AD, compare the group DN with the mapping entry, and confirm the nested group setting matches how membership is stored
User cannot log in with the name they use on their workstationLogin name format mismatch, such as the sAMAccountName, the user principal name and the mail address being used interchangeablyMatch the search filter attribute to the name users type, and document the accepted format for users so the filter and the help desk guidance agree
Connection times out or is refused before any search is loggedFirewall or port block between the Grafana host and the domain controller on the LDAP or LDAPS portTest the TCP connection from the Grafana host to each domain controller on the configured port, then open the required path in the network controls

Questions teams ask before configuring LDAP for Grafana

Does LDAP authentication work in open source Grafana?

Yes. LDAP is one of the authentication options available in every Grafana edition, according to the Grafana authentication docs. You configure it in ldap.toml on the Grafana server, so the directory connection, group mappings and TLS settings live with the rest of your self-hosted configuration. Confirm the exact options for your Grafana version in the Grafana authentication docs before you finalize the design, because option names and behavior can change between releases.

Do team sync and active sync require Grafana Enterprise?

Yes. According to the Grafana authentication docs, team sync and active sync are available only in Grafana Enterprise and Grafana Cloud, while basic LDAP login is available in all editions. In practice this means open source can map directory groups to organization roles at sign-in, but it does not keep Grafana teams synchronized with directory groups or remove access when a user is deactivated in the directory. If team-level access is central to your model, ask for that requirement to be scoped explicitly before you commit to an edition.

How long does LDAP setup take for an Active Directory domain?

The duration depends mostly on how well your directory structure matches the access model you want in Grafana. A single domain with a few well-named security groups is a short configuration task, while nested groups, several domains and strict role rules add testing and review cycles. Ask for a timeline that lists the group inventory, the test matrix and the TLS validation as separate steps, so you can see which items drive the schedule. Any figure should come from the written scope for your environment, not from a general estimate.

What does the team need to provide before configuration starts?

Most of the input comes from your identity team and your Grafana owners. Prepare the following:

  • A bind account with read access to the user and group attributes Grafana needs, and a documented password rotation process
  • The CA certificate that signed your domain controllers' certificates, so Grafana can validate LDAP over TLS
  • The list of directory groups and the Grafana organization and role each should receive
  • A set of test users covering each role, plus at least one user who should be denied

Having these ready before the engagement starts shortens the discovery phase considerably.

Can our own team configure LDAP for Grafana without a partner?

Yes, if your team has administrative access to the Grafana server, the directory and the certificate authority, and the time to test each role path. The configuration itself is a file change plus a restart, but the work that causes trouble is confirming group distinguished names, checking how attributes are returned and validating TLS. Teams with a small number of groups and a single domain often handle this internally. Teams with nested groups, multiple domains or a compliance requirement for documented testing often bring in help for the design and verification steps.

What makes an LDAP configuration more complex to build and test?

Complexity rises with the number of decisions the directory has to answer at sign-in. The main drivers are:

  • Nested groups, which need a lookup strategy that returns indirect membership
  • Multiple domains or forests, which need separate search bases, bind accounts and certificate chains
  • Strict role rules, where a user with no matching group should be denied or given the lowest role
  • Server administrator grants and organization mappings that must match your governance model

Each added rule multiplies the test cases, so ask for the test matrix to be part of the written scope.

How do we troubleshoot a failed LDAP login in Grafana?

Start by enabling LDAP debug logging on the Grafana server, reproduce the failed login with a known test user, and read the entries for the bind, the user search and the group lookup in order. Most failures fall into three groups: the bind account is rejected, the search base or filter does not match the user, or the TLS handshake fails because the CA certificate is not trusted. Compare the attribute names in the log with what your mapping expects, and test each change with the same user so the cause is isolated. Keep debug logging off in production once the cause is found, since it can record directory details you do not need to keep.

What LDAP covers in open source and what needs Grafana Enterprise

LDAP login works in every Grafana edition, so an open-source instance can authenticate users against Active Directory through ldap.toml without buying a license. The gap is in what happens after sign-in. Team sync, active sync and SCIM provisioning are documented as Grafana Enterprise and Grafana Cloud features, and SAML sits in the same tier. Before you design around any of them, check the current list in Grafana's authentication documentation and confirm licensing directly with Grafana Labs, since editions and feature placement change between releases.

Without those features, the team has to manage the identity lifecycle by hand. Users who leave Active Directory still hold Grafana accounts until someone disables them, because open-source LDAP authenticates at login and does not continuously deprovision. Team membership is not synchronized from directory groups, so people who move between teams need manual edits to Grafana teams. Group-to-role mapping in ldap.toml still works in open source, which covers most org role decisions, but any per-team dashboard permissions must be maintained by an administrator or by a script calling the Grafana API. Plan a periodic access review that compares directory group membership with Grafana users, teams and roles, and assign an owner to it.

Ask for a written inventory of the Grafana features you need before you commit to a design. If the answer depends on team sync or automated deprovisioning, price the Enterprise license and the manual process side by side, and record which controls each option supports. The question to put to Grafana Labs is which features your edition and deployment model include, and whether that changes across the upgrade cycle your team will follow. Treat the answer as a design input, not an assumption carried over from another identity setup.

How DeployOpen scopes and delivers Grafana LDAP authentication

A Grafana LDAP or Active Directory engagement is scoped in writing before any configuration changes. The work runs inside your own Grafana and directory environment, is tested with named accounts, and ends with documentation your team can operate. Each card below covers one step of that path and the decisions your team should make along the way.

Written fixed scope

Before work starts, the scope is agreed in writing. It records which directory the Grafana instance will bind to, whether a bind account or a single bind is used, which groups map to which organization roles, and which Grafana instances are covered. Ask for the written scope to list every item it excludes, such as SAML or team sync, which the Grafana authentication docs place in Enterprise and Grafana Cloud. Changes after sign-off should go through a written change request.

Configuration in your environment

The work is carried out inside your Grafana servers, your domain controllers and your network segments, not in a DeployOpen-hosted tenant. Your team keeps custody of the bind credentials, the CA certificate and the final ldap.toml. Confirm early which hosts can reach the directory on the LDAP and LDAPS ports, and which change window your organization requires for the Grafana service restart.

Testing with named accounts

Testing uses named test accounts drawn from each group that maps to a Grafana role or organization, plus accounts that should be denied. Each account is checked for the expected role, the expected org membership, and the expected denial when it is outside the allowed groups. Results are recorded per account so a failed login can be traced to a specific group, nested membership or certificate problem.

Documented ldap.toml and runbook

Delivery includes the final ldap.toml, with secrets referenced rather than embedded, a description of each group mapping, and a runbook covering how to enable LDAP debug logging, what the log lines mean, how to rotate the bind password and how to remove a user's access. Ask for the runbook to name the owner of each step, since directory and Grafana administrators often work on the same failure.

Retainer support for upgrades

Grafana releases new minor versions regularly, and configuration that worked on one release can need review on the next. An optional retainer covers upgrade testing of the LDAP settings, re-running the named-account tests after directory changes and responding to issues in the runbook. Ask what the retainer covers, how requests are prioritized, and whether it applies to the Grafana instances in your scope, since retainer terms are agreed separately from the fixed scope.

Talk to our team.

Tell us what you're working on, whether it's a deployment, an audit, a security test or a cyber range. You'll speak with an engineer who can help you scope it.

  • 30-minute call: free, with no obligation.
  • NDA on request: we can sign before you share details.
  • Clear next steps: a scope and plan after the call.