菜单
Grafana Cloud Enterprise 开源

配置 LDAP 认证

Grafana 中的 LDAP 集成允许 Grafana 用户使用其 LDAP 凭据登录。您还可以指定 LDAP 组成员身份和 Grafana 组织用户角色之间的映射。

请参阅基于角色的访问控制以了解如何使用基于角色的权限控制访问。

支持的 LDAP 服务器

Grafana 底层使用了一个支持基本 LDAP v3 功能的第三方 LDAP 库。这意味着您应该能够使用任何兼容 LDAPv3 的服务器配置 LDAP 集成,例如OpenLDAPActive Directory以及其他服务器。

启用 LDAP

为了使用 LDAP 集成,您首先需要在主配置文件中启用 LDAP,并指定 LDAP 特殊配置文件的路径(默认为:/etc/grafana/ldap.toml)。

启用 LDAP 后,默认行为是在 LDAP 认证成功时自动创建 Grafana 用户。如果您希望只有现有的 Grafana 用户能够登录,可以在 [auth.ldap] 部分将 allow_sign_up 更改为 false

ini
[auth.ldap]
# Set to `true` to enable LDAP integration (default: `false`)
enabled = true

# Path to the LDAP specific configuration file (default: `/etc/grafana/ldap.toml`)
config_file = /etc/grafana/ldap.toml

# Allow sign-up should be `true` (default) to allow Grafana to create users on successful LDAP authentication.
# If set to `false` only already existing Grafana users will be able to login.
allow_sign_up = true

禁用组织角色同步

如果您使用 LDAP 认证用户但不使用角色映射,并且希望手动分配组织和角色,可以使用 skip_org_role_sync 配置选项。

ini
[auth.ldap]
# Set to `true` to enable LDAP integration (default: `false`)
enabled = true

# Path to the LDAP specific configuration file (default: `/etc/grafana/ldap.toml`)
config_file = /etc/grafana/ldap.toml

# Allow sign-up should be `true` (default) to allow Grafana to create users on successful LDAP authentication.
# If set to `false` only already existing Grafana users will be able to login.
allow_sign_up = true

# Prevent synchronizing ldap users organization roles
skip_org_role_sync = true

Grafana LDAP 配置

根据您使用的 LDAP 服务器及其配置方式,您的 Grafana LDAP 配置可能会有所不同。有关更多信息,请参阅配置示例

LDAP 特定配置文件 (ldap.toml) 示例

bash
[[servers]]
# Ldap server host (specify multiple hosts space separated)
host = "ldap.my_secure_remote_server.org"
# Default port is 389 or 636 if use_ssl = true
port = 636
# Set to true if LDAP server should use an encrypted TLS connection (either with STARTTLS or LDAPS)
use_ssl = true
# If set to true, use LDAP with STARTTLS instead of LDAPS
start_tls = false
# The value of an accepted TLS cipher. By default, this value is empty. Example value: ["TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384"])
# For a complete list of supported ciphers and TLS versions, refer to: https://golang.ac.cn/src/crypto/tls/cipher_suites.go
# Starting with Grafana v11.0 only ciphers with ECDHE support are accepted for TLS 1.2 connections.
tls_ciphers = []
# This is the minimum TLS version allowed. By default, this value is empty. Accepted values are: TLS1.1 (only for Grafana v10.4 or earlier), TLS1.2, TLS1.3.
min_tls_version = ""
# set to true if you want to skip SSL cert validation
ssl_skip_verify = false
# set to the path to your root CA certificate or leave unset to use system defaults
# root_ca_cert = "/path/to/certificate.crt"
# Authentication against LDAP servers requiring client certificates
# client_cert = "/path/to/client.crt"
# client_key = "/path/to/client.key"

# Search user bind dn
bind_dn = "cn=admin,dc=grafana,dc=org"
# Search user bind password
# If the password contains # or ; you have to wrap it with triple quotes. Ex """#password;"""
bind_password = "grafana"
# We recommend using variable expansion for the bind_password, for more info https://grafana.org.cn/docs/grafana/latest/setup-grafana/configure-grafana/#variable-expansion
# bind_password = '$__env{LDAP_BIND_PASSWORD}'

# Timeout in seconds. Applies to each host specified in the 'host' entry (space separated).
timeout = 10

# User search filter, for example "(cn=%s)" or "(sAMAccountName=%s)" or "(uid=%s)"
# Allow login from email or username, example "(|(sAMAccountName=%s)(userPrincipalName=%s))"
search_filter = "(cn=%s)"

# An array of base dns to search through
search_base_dns = ["dc=grafana,dc=org"]

# group_search_filter = "(&(objectClass=posixGroup)(memberUid=%s))"
# group_search_filter_user_attribute = "distinguishedName"
# group_search_base_dns = ["ou=groups,dc=grafana,dc=org"]

# Specify names of the LDAP attributes your LDAP uses
[servers.attributes]
member_of = "memberOf"
email =  "email"

注意

每当您修改 ldap.toml 文件时,必须重启 Grafana 以使更改生效。

使用环境变量

您可以在 TOML 配置中通过环境变量插值变量。例如,您可以通过这种方式将 bind_password 外部化

bash
bind_password = "${LDAP_ADMIN_PASSWORD}"

LDAP 调试视图

Grafana 内置了 LDAP 调试视图,允许您直接在 Grafana 中测试您的 LDAP 配置。只有 Grafana 管理员可以使用 LDAP 调试视图。

在此视图中,您将能够看到哪些 LDAP 服务器当前可达,并测试您当前的配置。

LDAP testing

要使用调试视图,请完成以下步骤

  1. 输入在您的任何 LDAP 服务器中存在的用户的用户名
  2. 然后,按“运行”
  3. 如果在您的任何 LDAP 实例中找到该用户,则会显示映射信息。

请注意,如果您使用下述的单绑定配置,此功能不起作用。

LDAP mapping displayed

Grafana Enterprise 用户启用了增强型 LDAP 集成后,也可以在调试视图中看到同步状态。这需要 ldap.status:read 权限。

LDAP sync status

绑定和绑定密码

默认情况下,配置要求您指定一个绑定 DN 和绑定密码。这应该是一个只读用户,可以执行 LDAP 搜索。找到用户 DN 后,会使用用户提供的用户名和密码(在正常的 Grafana 登录表单中)执行第二次绑定。

bash
bind_dn = "cn=admin,dc=grafana,dc=org"
bind_password = "grafana"

单绑定示例

如果您可以提供一个匹配所有可能用户的单绑定表达式,您可以跳过第二次绑定,直接使用用户 DN 进行绑定。这样您就不需要在配置文件中指定 bind_password

bash
bind_dn = "cn=%s,o=users,dc=grafana,dc=org"

在这种情况下,您跳过提供 bind_password,而是提供一个包含 %sbind_dn 值。这将被 Grafana 登录页面中输入的用户名替换。仍然需要搜索过滤器和搜索基本设置来执行 LDAP 搜索以检索其他 LDAP 信息(如 LDAP 组和电子邮件)。

POSIX 模式

如果您的 LDAP 服务器不支持 memberOf 属性,请添加以下选项

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

组映射

[[servers.group_mappings]] 中,您可以将 LDAP 组映射到 Grafana 组织和角色。这些将在用户每次登录时同步,以 LDAP 作为权威来源。

LDAP 用户匹配到的第一个组映射将用于同步。如果您的 LDAP 用户匹配多个映射,将使用 TOML 配置中最顶部的映射。

LDAP 特定配置文件 (ldap.toml) 示例

bash
[[servers]]
# other settings omitted for clarity

[[servers.group_mappings]]
group_dn = "cn=superadmins,dc=grafana,dc=org"
org_role = "Admin"
grafana_admin = true

[[servers.group_mappings]]
group_dn = "cn=admins,dc=grafana,dc=org"
org_role = "Admin"

[[servers.group_mappings]]
group_dn = "cn=users,dc=grafana,dc=org"
org_role = "Editor"

[[servers.group_mappings]]
group_dn = "*"
org_role = "Viewer"
设置必需描述默认值
group_dnLDAP 组的 LDAP 可分辨名称 (DN)。如果您想匹配所有(或不匹配任何 LDAP 组),可以使用通配符 ("*")
org_rolegroup_dn 中的用户分配组织角色为 AdminEditorViewer。组织角色名称区分大小写。
org_idGrafana 组织数据库 ID。设置此项允许将多个 group_dn 分配给相同的 org_role,前提是 org_id 不同1 (默认组织 ID)
grafana_admin当为 true 时,使 group_dn 中的用户成为 Grafana 服务器管理员。Grafana 服务器管理员对所有组织和用户具有管理权限。false

注意

注释掉一个组映射时,也需要注释掉该组的头部,否则将作为空映射验证失败。

示例

bash
[[servers]]
# other settings omitted for clarity

[[servers.group_mappings]]
group_dn = "cn=superadmins,dc=grafana,dc=org"
org_role = "Admin"
grafana_admin = true

# [[servers.group_mappings]]
# group_dn = "cn=admins,dc=grafana,dc=org"
# org_role = "Admin"

[[servers.group_mappings]]
group_dn = "cn=users,dc=grafana,dc=org"
org_role = "Editor"

嵌套/递归组关系

具有嵌套/递归组关系的用户必须拥有支持 LDAP_MATCHING_RULE_IN_CHAIN 的 LDAP 服务器,并以一种返回提交用户名所属组的方式配置 group_search_filter

要配置 group_search_filter

  • 您可以设置 group_search_base_dns 来指定匹配的组在哪里定义。
  • 如果您不使用 group_search_base_dns,则使用之前定义的 search_base_dns

Active Directory 示例

Active Directory 组存储成员的可分辨名称 (DN),因此您的过滤器需要仅根据提交的用户名知道用户的 DN。通过使用 LDAP OR 运算符组合过滤器来搜索多个 DN 模板。两个示例

bash
group_search_filter = "(member:1.2.840.113556.1.4.1941:=%s)"
group_search_base_dns = ["DC=mycorp,DC=mytld"]
group_search_filter_user_attribute = "dn"
bash
group_search_filter = "(member:1.2.840.113556.1.4.1941:=CN=%s,[user container/OU])"
group_search_filter = "(|(member:1.2.840.113556.1.4.1941:=CN=%s,[user container/OU])(member:1.2.840.113556.1.4.1941:=CN=%s,[another user container/OU]))"
group_search_filter_user_attribute = "cn"

有关 AD 搜索的更多信息,请参阅Microsoft 的搜索过滤器语法文档。

为了故障排除,将 [servers.attributes] 中的 member_of 更改为“dn”,可以在启用调试时显示更准确的组关系。

配置示例

以下示例描述了不同的 LDAP 配置选项。

OpenLDAP

OpenLDAP 是一个开源目录服务。

LDAP 特定配置文件 (ldap.toml)

bash
[[servers]]
host = "127.0.0.1"
port = 389
use_ssl = false
start_tls = false
ssl_skip_verify = false
bind_dn = "cn=admin,dc=grafana,dc=org"
bind_password = "grafana"
search_filter = "(cn=%s)"
search_base_dns = ["dc=grafana,dc=org"]

[servers.attributes]
member_of = "memberOf"
email =  "email"

# [[servers.group_mappings]] omitted for clarity

多个 LDAP 服务器

Grafana 支持从多个 LDAP 服务器接收信息。

LDAP 特定配置文件 (ldap.toml)

bash
# --- First LDAP Server ---

[[servers]]
host = "10.0.0.1"
port = 389
use_ssl = false
start_tls = false
ssl_skip_verify = false
bind_dn = "cn=admin,dc=grafana,dc=org"
bind_password = "grafana"
search_filter = "(cn=%s)"
search_base_dns = ["ou=users,dc=grafana,dc=org"]

[servers.attributes]
member_of = "memberOf"
email =  "email"

[[servers.group_mappings]]
group_dn = "cn=admins,ou=groups,dc=grafana,dc=org"
org_role = "Admin"
grafana_admin = true

# --- Second LDAP Server ---

[[servers]]
host = "10.0.0.2"
port = 389
use_ssl = false
start_tls = false
ssl_skip_verify = false

bind_dn = "cn=admin,dc=grafana,dc=org"
bind_password = "grafana"
search_filter = "(cn=%s)"
search_base_dns = ["ou=users,dc=grafana,dc=org"]

[servers.attributes]
member_of = "memberOf"
email =  "email"

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

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

Active Directory

Active Directory 是一个在 Windows 环境中常用的目录服务。

假设以下 Active Directory 服务器设置

  • IP 地址:10.0.0.1
  • 域:CORP
  • DNS 名称:corp.local

LDAP 特定配置文件 (ldap.toml)

bash
[[servers]]
host = "10.0.0.1"
port = 3269
use_ssl = true
start_tls = false
ssl_skip_verify = true
bind_dn = "CORP\\%s"
search_filter = "(sAMAccountName=%s)"
search_base_dns = ["dc=corp,dc=local"]

[servers.attributes]
member_of = "memberOf"
email =  "mail"

# [[servers.group_mappings]] omitted for clarity

端口要求

在前面的示例中,启用了 SSL 并配置了加密端口。如果您的 Active Directory 不支持 SSL,请改为使用 enable_ssl = falseport = 389

检查您的 Active Directory 配置和文档以找到正确的设置。有关 Active Directory 和端口要求的更多信息,请参阅Microsoft 文档

故障排除

要排除故障并获取更多日志信息,请在grafana.inicustom.ini 文件中启用 LDAP 调试日志记录

bash
[log]
filters = ldap:debug