LDAP Authentication

    Grafana uses a under the hood that supports basic LDAP v3 functionality. This means that you should be able to configure LDAP integration using any compliant LDAPv3 server, for example OpenLDAP or among others.

    Enable LDAP

    In order to use LDAP integration you’ll first need to enable LDAP in the main config file as well as specify the path to the LDAP specific configuration file (default: ).

    Depending on which LDAP server you’re using and how that’s configured your Grafana LDAP configuration may vary. See configuration examples for more information.

    LDAP specific configuration file (ldap.toml) example:

    1. [[servers]]
    2. # Ldap server host (specify multiple hosts space separated)
    3. host = "127.0.0.1"
    4. # Default port is 389 or 636 if use_ssl = true
    5. port = 389
    6. # Set to true if LDAP server should use an encrypted TLS connection (either with STARTTLS or LDAPS)
    7. use_ssl = false
    8. # If set to true, use LDAP with STARTTLS instead of LDAPS
    9. start_tls = false
    10. # set to true if you want to skip SSL cert validation
    11. ssl_skip_verify = false
    12. # set to the path to your root CA certificate or leave unset to use system defaults
    13. # root_ca_cert = "/path/to/certificate.crt"
    14. # Authentication against LDAP servers requiring client certificates
    15. # client_cert = "/path/to/client.crt"
    16. # client_key = "/path/to/client.key"
    18. # Search user bind dn
    19. bind_dn = "cn=admin,dc=grafana,dc=org"
    20. # Search user bind password
    21. # If the password contains # or ; you have to wrap it with triple quotes. Ex """#password;"""
    22. bind_password = 'grafana'
    24. # User search filter, for example "(cn=%s)" or "(sAMAccountName=%s)" or "(uid=%s)"
    25. # Allow login from email or username, example "(|(sAMAccountName=%s)(userPrincipalName=%s))"
    26. search_filter = "(cn=%s)"
    28. # An array of base dns to search through
    29. search_base_dns = ["dc=grafana,dc=org"]
    31. # group_search_filter = "(&(objectClass=posixGroup)(memberUid=%s))"
    32. # group_search_filter_user_attribute = "distinguishedName"
    33. # group_search_base_dns = ["ou=groups,dc=grafana,dc=org"]
    35. # Specify names of the LDAP attributes your LDAP uses
    36. [servers.attributes]
    37. member_of = "memberOf"
    38. email =  "email"

    You can interpolate variables in the TOML configuration from environment variables. For instance, you could externalize your bind_password that way:

    1. bind_password = "${LDAP_ADMIN_PASSWORD}"

    LDAP Debug View

    Only available in Grafana v6.4+

    Grafana has an LDAP debug view built-in which allows you to test your LDAP configuration directly within Grafana. At the moment of writing, only Grafana admins can use the LDAP debug view.

    Within this view, you’ll be able to see which LDAP servers are currently reachable and test your current configuration.

    LDAP Authentication - 图2

    1. Then, press “Run”

    2. If the user is found within any of your LDAP instances, the mapping information is displayed

      LDAP Authentication - 图4

    Bind

    Bind and Bind Password

    By default the configuration expects you to specify a bind DN and bind password. This should be a read only user that can perform LDAP searches. When the user DN is found a second bind is performed with the user provided username and password (in the normal Grafana login form).

    1. bind_dn = "cn=admin,dc=grafana,dc=org"
    2. bind_password = "grafana"

    Single Bind Example

    If you can provide a single bind expression that matches all possible users, you can skip the second bind and bind against the user DN directly. This allows you to not specify a bind_password in the configuration file.

    In this case you skip providing a bind_password and instead provide a bind_dn value with a %s somewhere. This will be replaced with the username entered in on the Grafana login page. The search filter and search bases settings are still needed to perform the LDAP search to retrieve the other LDAP information (like LDAP groups and email).

    If your LDAP server does not support the memberOf attribute add these options:

    1. ## Group search filter, to retrieve the groups of which the user is a member (only set if memberOf attribute is not available)
    2. group_search_filter = "(&(objectClass=posixGroup)(memberUid=%s))"
    3. ## An array of the base DNs to search through for groups. Typically uses ou=groups
    4. group_search_base_dns = ["ou=groups,dc=grafana,dc=org"]
    5. ## the %s in the search filter will be replaced with the attribute defined below
    6. group_search_filter_user_attribute = "uid"

    Group Mappings

    In [[servers.group_mappings]] you can map an LDAP group to a Grafana organization and role. These will be synced every time the user logs in, with LDAP being the authoritative source. So, if you change a user’s role in the Grafana Org. Users page, this change will be reset the next time the user logs in. If you change the LDAP groups of a user, the change will take effect the next time the user logs in.

    The first group mapping that an LDAP user is matched to will be used for the sync. If you have LDAP users that fit multiple mappings, the topmost mapping in the TOML configuration will be used.

    LDAP specific configuration file (ldap.toml) example:

    1. [[servers]]
    2. # other settings omitted for clarity
    4. [[servers.group_mappings]]
    5. group_dn = "cn=superadmins,dc=grafana,dc=org"
    6. org_role = "Admin"
    7. grafana_admin = true # Available in Grafana v5.3 and above
    9. [[servers.group_mappings]]
    10. group_dn = "cn=admins,dc=grafana,dc=org"
    11. org_role = "Admin"
    13. [[servers.group_mappings]]
    14. group_dn = "cn=users,dc=grafana,dc=org"
    15. org_role = "Editor"
    17. [[servers.group_mappings]]
    18. group_dn = "*"
    19. org_role = "Viewer"

    Users with nested/recursive group membership must have an LDAP server that supports LDAP_MATCHING_RULE_IN_CHAIN and configure group_search_filter in a way that it returns the groups the submitted username is a member of.

    To configure group_search_filter:

    • You can set group_search_base_dns to specify where the matching groups are defined.
    • If you do not use group_search_base_dns, then the previously defined search_base_dns is used.

    Active Directory groups store the Distinguished Names (DNs) of members, so your filter will need to know the DN for the user based only on the submitted username. Multiple DN templates can be searched by combining filters with the LDAP OR-operator. Two examples:

    1. group_search_filter = "(member:1.2.840.113556.1.4.1941:=%s)"
    2. group_search_base_dns = ["DC=mycorp,DC=mytld"]
    3. group_search_filter_user_attribute = "dn"

    For more information on AD searches see documentation.

    For troubleshooting, by changing member_of in [servers.attributes] to “dn” it will show you more accurate group memberships when debug is enabled.

    OpenLDAP

    is an open source directory service.

    LDAP specific configuration file (ldap.toml):

    1. [[servers]]
    2. host = "127.0.0.1"
    3. port = 389
    4. use_ssl = false
    5. start_tls = false
    6. ssl_skip_verify = false
    7. bind_dn = "cn=admin,dc=grafana,dc=org"
    8. bind_password = 'grafana'
    9. search_filter = "(cn=%s)"
    10. search_base_dns = ["dc=grafana,dc=org"]
    12. [servers.attributes]
    13. member_of = "memberOf"
    14. email =  "email"
    16. # [[servers.group_mappings]] omitted for clarity

    Grafana does support receiving information from multiple LDAP servers.

    LDAP specific configuration file (ldap.toml):

    1. # --- First LDAP Server ---
    3. [[servers]]
    4. host = "10.0.0.1"
    5. port = 389
    6. use_ssl = false
    7. ssl_skip_verify = false
    8. bind_dn = "cn=admin,dc=grafana,dc=org"
    9. bind_password = 'grafana'
    10. search_filter = "(cn=%s)"
    11. search_base_dns = ["ou=users,dc=grafana,dc=org"]
    13. [servers.attributes]
    14. member_of = "memberOf"
    15. email =  "email"
    17. [[servers.group_mappings]]
    18. group_dn = "cn=admins,ou=groups,dc=grafana,dc=org"
    19. org_role = "Admin"
    20. grafana_admin = true
    22. # --- Second LDAP Server ---
    24. [[servers]]
    25. host = "10.0.0.2"
    26. port = 389
    27. use_ssl = false
    28. start_tls = false
    29. ssl_skip_verify = false
    31. bind_dn = "cn=admin,dc=grafana,dc=org"
    32. bind_password = 'grafana'
    33. search_filter = "(cn=%s)"
    34. search_base_dns = ["ou=users,dc=grafana,dc=org"]
    36. [servers.attributes]
    37. member_of = "memberOf"
    38. email =  "email"
    40. [[servers.group_mappings]]
    41. group_dn = "cn=editors,ou=groups,dc=grafana,dc=org"
    42. org_role = "Editor"
    44. [[servers.group_mappings]]
    45. group_dn = "*"
    46. org_role = "Viewer"

    Active Directory

    Active Directory is a directory service which is commonly used in Windows environments.

    Assuming the following Active Directory server setup:

    • IP address: 10.0.0.1
    • Domain: CORP
    • DNS name: corp.local

    LDAP specific configuration file (ldap.toml):

    1. [[servers]]
    2. host = "10.0.0.1"
    3. port = 3269
    4. use_ssl = true
    5. start_tls = false
    6. ssl_skip_verify = true
    7. bind_dn = "CORP\\%s"
    8. search_filter = "(sAMAccountName=%s)"
    9. search_base_dns = ["dc=corp,dc=local"]
    11. [servers.attributes]
    12. member_of = "memberOf"
    13. email =  "mail"
    14. # [[servers.group_mappings]] omitted for clarity

    Port requirements

    In above example SSL is enabled and an encrypted port have been configured. If your Active Directory don’t support SSL please change enable_ssl = false and . Please inspect your Active Directory configuration and documentation to find the correct settings. For more information about Active Directory and port requirements see link.

    Troubleshooting