Grafana 专题【左扬精讲】—— 提升 Grafana 安全性:LDAP 升级 LDAPS 的核心步骤与常见问题解决
https://grafana.com/docs/grafana/next/setup-grafana/configure-security/configure-authentication/ldap/
https://grafana.com/docs/grafana/next/setup-grafana/configure-security/configure-authentication/ldap-ui/#4-extra-security-settings
在 Grafana 运维场景中,LDAP(轻量级目录访问协议)是常用的集中式认证方案,但默认的 LDAP 采用明文传输,存在账号密码被窃取的安全风险。而 LDAPS(基于 SSL/TLS 的 LDAP)通过加密通道传输数据,能有效规避这一隐患。本文将结合 Grafana 官网最新文档,详细讲解从 LDAP 升级到 LDAPS 的核心步骤、验证方法,以及实战中常见问题的解决方案。
一、升级前的核心准备:明确前提与环境检查
在启动升级前,需确保满足 Grafana 对 LDAPS 的基础要求,避免因环境不兼容导致升级失败。根据官网文档,核心准备工作包含以下三点:
1.1、确认 Grafana 版本兼容性
Grafana 从 v2.1 版本开始支持 LDAP 认证,而 LDAPS 作为 LDAP 的加密扩展,无需额外版本依赖 ——只要当前 Grafana 已正常使用 LDAP,即可直接升级为 LDAPS。
建议先通过以下命令确认 Grafana 版本,确保为稳定版(推荐 v6.4+,支持 LDAP 调试视图,便于后续验证):
grafana-server -v # 输出示例:Grafana v10.2.0 (commit: 1234567, branch: HEAD)
1.2、准备 LDAPS 服务端基础条件
LDAPS 依赖 SSL/TLS 证书实现加密,需确保你的 LDAP 服务器已满足以下条件:
-
- 已配置有效的 SSL/TLS 证书(可使用自签名证书,或 Let's Encrypt 等权威机构颁发的证书);
- 已开启 LDAPS 端口(默认端口为 636,需确认防火墙已放行该端口,避免网络拦截);
- 证书格式符合 Grafana 要求(支持 PEM 格式,需包含完整的证书链,避免 “证书不信任” 问题)。
1.3、备份原有 LDAP 配置
为避免升级失败影响现有认证功能,需先备份 Grafana 原有的 LDAP 配置文件。默认配置路径如下(不同部署方式路径可能不同,以实际环境为准):
# 备份 Grafana 主配置文件(含 LDAP 开关配置) cp /etc/grafana/grafana.ini /etc/grafana/grafana.ini.bak-ldap# 备份 LDAP 详细配置文件 cp /etc/grafana/ldap.toml /etc/grafana/ldap.toml.bak-ldap
二、升级核心步骤:从 LDAP 到 LDAPS 的配置修改
根据 Grafana 官网规范,LDAPS 配置需通过 "主配置文件(grafana.ini)+ LDAP 详细配置文件(ldap.toml)" 协同实现,核心是启用 SSL 加密并指向正确的证书文件。以下是分步操作指南:
2.1、步骤 1:启用 Grafana LDAP 认证(基础开关确认)
首先确认 grafana.ini 中 LDAP 认证已启用(升级前通常已配置,此处仅需二次校验):
1、打开 Grafana 主配置文件:
vim /etc/grafana/grafana.ini
2、定位到 "auth.ldap" 模块,确保以下配置项正确:
[auth.ldap] enabled = true # 必须设为 true,启用 LDAP 认证 config_file = /etc/grafana/ldap.toml # LDAP 详细配置文件路径,默认无需修改 allow_sign_up = true # 允许 LDAP 用户首次登录时自动创建 Grafana 账号(按需开启)
3、保存退出,此步骤仅需确保 LDAP 基础功能已开启,无需额外新增配置。
2.2、步骤 2:修改 ldap.toml,配置 LDAPS 加密参数
ldap.toml 是 LDAP 认证的核心配置文件,升级 LDAPS 的关键修改集中在此文件。打开文件后,按以下要求调整配置(重点关注 host、port、use_ssl、ssl_ca_cert 等参数):
2.2.1、基础连接配置:从 “明文 LDAP” 切换为 “加密 LDAPS”
原 LDAP 配置(明文,默认端口 389)通常如下:
[[servers]] host = "your-ldap-server-ip" # 你的 LDAP 服务器 IP/域名 port = 389 # LDAP 明文端口 use_ssl = false # 原配置为 false,不启用 SSL
升级为 LDAPS 后,需修改为:
[[servers]] host = "your-ldap-server-ip" # 保持与原 LDAP 服务器一致 port = 636 # 改为 LDAPS 默认端口 636 use_ssl = true # 启用 SSL 加密,核心开关
2.2.2、证书配置:解决 “SSL 证书不信任” 问题
根据官网文档,Grafana 会验证 LDAPS 服务器的 SSL 证书,若证书未被系统信任(如自签名证书),需手动指定证书路径。在 [[servers]] 模块下新增 / 修改以下配置:
# 方案 1:使用 LDAPS 服务器的 CA 证书(推荐,安全性高) ssl_ca_cert = "/etc/grafana/certs/ldap-ca.pem" # 存放 LDAP 服务器 CA 证书的路径# 方案 2:跳过证书验证(仅测试环境临时使用,生产环境禁用!) # ssl_skip_verify = true # 生产环境启用会导致“中间人攻击”风险,官网明确不推荐
证书获取方法:从 LDAP 服务器导出 CA 证书(如 OpenLDAP 可通过 slapcat 命令导出,Active Directory 可从域控制器获取),并将证书文件上传至 Grafana 服务器的 /etc/grafana/certs/ 目录(需确保 grafana 用户有读权限):
# 给证书文件设置正确权限 chown grafana:grafana /etc/grafana/certs/ldap-ca.pem chmod 644 /etc/grafana/certs/ldap-ca.pem
2.3、保持原有用户映射配置不变
LDAPS 仅改变传输加密方式,不影响用户认证逻辑,因此原 LDAP 配置中的「用户搜索」「组映射」等参数无需修改。例如:
# 原有用户搜索配置(无需修改) [servers.attributes] name = "givenName" surname = "sn" username = "cn" email = "mail"# 原有组映射配置(无需修改,确保 LDAP 用户能正确关联 Grafana 角色) [[servers.group_mappings]] group_dn = "cn=grafana-admins,ou=groups,dc=example,dc=com" org_role = "Admin" # 映射为 Grafana 管理员角色 org_id = 1[[servers.group_mappings]] group_dn = "cn=grafana-editors,ou=groups,dc=example,dc=com" org_role = "Editor" # 映射为 Grafana 编辑角色 org_id = 1
2.3、步骤 3:重启 Grafana 服务,使配置生效
修改完配置后,需重启 Grafana 服务,让 LDAPS 配置生效:
# 重启 Grafana 服务(systemd 部署方式) sudo systemctl restart grafana-server# 验证服务是否启动成功 sudo systemctl status grafana-server # 显示“active (running)”即为正常
三、升级后验证:确认 LDAPS 已实际生效
配置完成后,需通过 “服务日志检查”“功能测试”“工具验证” 三层确认 LDAPS 已正常工作,避免 “配置生效但实际未加密” 的隐患。
3.1、查看 Grafana 日志,确认无 LDAPS 连接错误
Grafana 日志会详细记录 LDAP 认证过程,通过日志可快速定位配置问题。默认日志路径为 /var/log/grafana/grafana.log,执行以下命令筛选 LDAP 相关日志:
tail -f /var/log/grafana/grafana.log | grep -i "ldap"
正常日志表现:无 TLS handshake failed(SSL 握手失败)、x509: certificate signed by unknown authority(证书不被信任)等错误,且包含以下成功信息:
# 示例:LDAPS 配置加载成功 INFO[0000] LDAP enabled, reading config file: /etc/grafana/ldap.toml logger=auth.ldap# 示例:LDAPS 连接成功(用户登录时触发) INFO[0123] LDAP user found: cn=test-user,ou=users,dc=example,dc=com logger=auth.ldap
异常日志排查:若出现 TLS handshake failed,需检查 LDAPS 端口是否放行、证书是否过期;若出现 certificate signed by unknown authority,需确认 ssl_ca_cert 路径是否正确、证书是否完整。
3.2、使用 Grafana 管理员调试视图验证
Grafana v6.4+ 提供了 LDAP 调试功能,管理员可直接在界面中测试 LDAPS 连接是否正常,步骤如下:
-
-
-
- 使用 Grafana 本地管理员账号(非 LDAP 账号)登录 Grafana;
- 进入「Server Admin」→「LDAP」(左侧菜单栏,需管理员权限);
- 在「Test LDAP Query」输入框中,输入一个已存在的 LDAP 用户名(如 test-user),点击「Run」;
- 正常结果:下方显示 “User found”,并列出用户的 DN、Email、Role 等信息,说明 LDAPS 能成功查询用户数据;
- 异常结果:显示 “User not found” 或 “Connection error”,需返回检查 ldap.toml 中的 host、port 或证书配置。
-
-
3.3、使用命令行工具测试 LDAPS 连接
在 Grafana 服务器上,通过 openssl 或 ldapsearch 工具直接测试与 LDAPS 服务器的连接,排除 Grafana 配置外的网络或服务端问题:
# 1. 使用 openssl 测试 SSL 握手与证书(核心验证加密通道) openssl s_client -connect your-ldap-server-ip:636 -showcerts# 正常输出:显示“SSL handshake has read 1234 bytes and written 567 bytes”,且无“verify error” # 异常输出:显示“Connection refused”(端口未开)或“verify return:1 (self signed certificate)”(证书未信任)# 2. 使用 ldapsearch 测试 LDAPS 查询(需安装 ldap-utils 包) ldapsearch -H ldaps://your-ldap-server-ip:636 -x -D "cn=admin,dc=example,dc=com" -W -b "ou=users,dc=example,dc=com" "cn=test-user"# 参数说明: # -H:指定 LDAPS 连接地址 # -D:LDAP 管理员 DN(用于绑定查询) # -W:手动输入 LDAP 管理员密码 # -b:查询的基准 DN(用户所在 OU) # 正常输出:返回 test-user 的详细属性信息,说明 LDAPS 服务端正常
四、常见问题与解决方案
在 LDAP 升级 LDAPS 过程中,容易遇到证书不信任、端口拦截、配置冲突等问题,以下是高频问题的解决方案:
4.1、问题 1:Grafana 日志报错 “x509: certificate signed by unknown authority”
原因:Grafana 无法验证 LDAPS 服务器的 SSL 证书(通常是自签名证书未配置 CA 路径)。
解决方案:
- 确认 ldap.toml 中 ssl_ca_cert 指向的 CA 证书路径正确;
- 若使用自签名证书,需确保证书文件包含完整的证书链(而非仅服务器证书);
- 执行 cat /etc/grafana/certs/ldap-ca.pem 检查证书内容,确保无格式错误(如缺少 -----BEGIN CERTIFICATE----- 头)。
4.2、问题 2:Grafana 服务重启后,LDAP 用户无法登录,日志显示 “TLS handshake failed”
原因:LDAPS 端口(636)被防火墙拦截,或 LDAP 服务器未启用 LDAPS 服务。
解决方案:
- 在 Grafana 服务器上测试端口连通性:telnet your-ldap-server-ip 636(正常应显示 “Connected to...”);
- 若端口不通,在 LDAP 服务器上开放 636 端口(如 iptables 配置:sudo iptables -A INPUT -p tcp --dport 636 -j ACCEPT);
- 确认 LDAP 服务器已启用 LDAPS(如 OpenLDAP 需配置 slapd.conf 中的 TLSCertificateFile 和 TLSCertificateKeyFile)。
4.3、问题 3:Grafana 调试视图显示 “User not found”,但 LDAP 服务器中存在该用户
原因:ldap.toml 中的「用户搜索配置」与 LDAPS 服务器的目录结构不匹配,导致查询不到用户。
解决方案:
4.3.1、检查 ldap.toml 中 [[servers]] 下的 search_filter 和 search_base_dns 配置
# 示例:正确的用户搜索配置(需与 LDAP 目录结构匹配) search_filter = "(cn=%s)" # 搜索条件,%s 代表输入的用户名 search_base_dns = ["ou=users,dc=example,dc=com"] # 用户所在的基准 DN,需与实际一致
4.3.2、使用 ldapsearch 工具验证搜索条件是否正确
ldapsearch -H ldaps://your-ldap-server-ip:636 -x -b "ou=users,dc=example,dc=com" "cn=test-user"
若该命令能查询到用户,说明搜索条件正确,需检查 Grafana 配置是否与命令参数一致。
4.4、问题 4:启用 LDAPS 后,Grafana 服务启动失败,日志显示 “open /etc/grafana/certs/ldap-ca.pem: permission denied”
原因:grafana 用户对 CA 证书文件没有读取权限。
解决方案:
4.4.1、执行以下命令,给证书文件赋予 grafana 用户读权限
chown grafana:grafana /etc/grafana/certs/ldap-ca.pem chmod 644 /etc/grafana/certs/ldap-ca.pem
重启 Grafana 服务:sudo systemctl restart grafana-server。
五、总结:LDAPS 升级后的安全最佳实践
-
- 禁用明文 LDAP 端口:升级完成后,建议在 LDAP 服务器上关闭 389 端口,强制所有客户端使用 LDAPS 连接;
- 定期更新 SSL 证书:避免证书过期导致认证失败,可通过监控工具(如 Prometheus + Alertmanager)监控证书有效期;
- 不使用 ssl_skip_verify:生产环境中严禁启用 “跳过证书验证”,防止中间人攻击;
- 定期备份配置文件:每次修改 grafana.ini 或 ldap.toml 后,及时备份,便于回滚。