Metabase LDAP 认证故障排查:从环境配置到源码级错误定位
Metabase LDAP 认证故障排查:从环境配置到源码级错误定位
Metabase 支持通过 LDAP(Lightweight Directory Access Protocol)完成企业级统一身份认证,本文以官方故障排查文档为主体,系统梳理 LDAP 认证的完整配置方式(docker-compose 一键起环境、Admin 面板手工配置、环境变量注入三种路径),并结合仓库源码逐条解析连接测试背后的错误定位逻辑与已知限制,帮助读者在 LDAP 登录异常时快速锁定问题根因。读完本文,你将掌握一套可复现的 LDAP 排障实验环境、一份完整的 MB_LDAP_* 环境变量对照表,以及"保存配置即校验、错误信息即答案"的排障方法论。
Metabase 的 LDAP 功能属于开源版内置能力,启用入口在 Admin > Settings > Authentication > LDAP。完整的配置步骤参见 LDAP 配置指南;若问题与 LDAP 无关(例如所有登录方式都失败),请直接参阅 登录故障排查指南。
一、LDAP 排障实验环境:一条命令拉起 Metabase + OpenLDAP
要在受控环境中复现并排查 LDAP 登录问题,最有效的方式是使用官方文档提供的 docker-compose 定义,在同一网络中同时启动 Metabase 容器与 Bitnami 的 OpenLDAP 容器。以下配置完整来自 docs/troubleshooting-guide/ldap.md,可直接保存为 docker-compose.yml 使用:
version: "3.7"
services:
metabase-ldap:
image: metabase/metabase:latest
container_name: metabase-ldap
hostname: metabase-ldap
volumes:
- /dev/urandom:/dev/random:ro
ports:
- 3000:3000
networks:
- metanet1
environment:
- "MB_LDAP_BIND_DN=cn=admin,dc=example,dc=org"
- "MB_LDAP_ENABLED=true"
- "MB_LDAP_GROUP_BASE=cn=readers"
- "MB_LDAP_HOST=openldap"
- "MB_LDAP_PASSWORD=adminpassword"
- "MB_LDAP_PORT=1389"
- "MB_LDAP_USER_BASE=ou=users,dc=example,dc=org"
- "MB_LDAP_ATTRIBUTE_EMAIL=uid"
# We are using the same field for email and first name, just for this example to work without modifications to the LDAP objects
- "MB_LDAP_ATTRIBUTE_FIRSTNAME=uid"
- "MB_LDAP_ATTRIBUTE_LASTNAME=sn"
openldap:
image: bitnamilegacy/openldap:2.4.57
hostname: openldap
container_name: openldap
ports:
- 1389:1389
environment:
- LDAP_ADMIN_USERNAME=admin
- LDAP_ADMIN_PASSWORD=adminpassword
- LDAP_USERS=user01@metabase.com,user02@metabase.com
- LDAP_PASSWORDS=password1!,password2!
- LDAP_PORT_NUMBER=1389
- LDAP_ROOT=dc=example,dc=org
- LDAP_USER_DC=users
- LDAP_GROUP=readers
networks:
- metanet1
networks:
metanet1:
driver: bridge
这套环境的关键设计点:
- Metabase 与 OpenLDAP 处于同一 bridge 网络
metanet1,Metabase 通过容器名openldap(MB_LDAP_HOST=openldap)访问目录服务,因此无需暴露 LDAP 端口到宿主机; MB_LDAP_PORT=1389对应 OpenLDAP 容器内配置的LDAP_PORT_NUMBER=1389;MB_LDAP_ATTRIBUTE_EMAIL=uid与MB_LDAP_ATTRIBUTE_FIRSTNAME=uid复用同一个字段:示例中 LDAP 用户user01@metabase.com的uid属性恰好是完整的邮箱地址,于是 Metabase 可以直接用uid同时充当用户的 email 与 first name,无需再修改 LDAP 对象结构。这种"属性复用"是快速验证的实用技巧;- OpenLDAP 侧通过 Bitnami 环境变量预置了
ou=users组织单元下的两个测试用户(user01@metabase.com/password1!与user02@metabase.com/password2!)以及readers用户组,对应 Metabase 配置里的MB_LDAP_USER_BASE与MB_LDAP_GROUP_BASE。
启动后用 docker compose up -d 拉起两个容器,访问 http://localhost:3000 即可用上述测试账号验证 LDAP 登录,把故障在本地最小化复现。
二、Admin 面板手工配置:字段含义与最小取值
如果不希望通过环境变量注入配置,也可以在 Metabase 管理界面逐项填写。进入 Admin > Settings > Authentication > LDAP Configuration,按文档给出的示例值填入(对应上文 docker-compose 中的同一套 LDAP 目录):
| 配置字段 | 示例值 |
|---|---|
USERNAME OR DN |
cn=admin,dc=example,dc=org |
PASSWORD |
adminpassword |
USER SEARCH BASE |
ou=users,dc=example,dc=org |
USER FILTER |
(&(objectClass=inetOrgPerson)(|(uid={login}))) |
GROUP SEARCH BASE |
cn=readers |
其中几个字段的正确理解直接决定排障方向:
USERNAME OR DN(bind DN):Metabase 用它绑定到 LDAP 目录,以便在登录时替用户执行搜索。源码中对应 settings.clj 的ldap-bind-dn设置:"The Distinguished Name to bind as (if any), this user will be used to lookup information about other users"。允许为空——此时 Metabase 会尝试匿名绑定。USER SEARCH BASE:用户搜索起点 DN,Metabase 会递归搜索该子树(源码注释为 "(Will be searched recursively)")。配置错误(如写成dc=example,dc=org而用户实际在ou=users下)并不会导致"查不到人"那么明显,而是取决于对象是否可被递归命中。USER FILTER:用户查找过滤器,{login}占位符会在登录时被替换为用户输入的账号。文档特别说明:可以保留默认值,默认过滤器会同时在uid和email两个字段中查找用户 ID,即:
(&(objectClass=inetOrgPerson)(|(uid={login})(mail={login})))
这一默认值定义在 settings.clj 中,同时也会显示在管理界面的 USER FILTER 输入框中(灰色只读样式)。示例中省略了 (mail={login}) 分支,仅用 uid 匹配——因为上文提到示例 LDAP 用户的 uid 就是邮箱地址。
保存配置即自动校验
值得强调的是,Metabase 的 LDAP 配置不是保存后静默生效的。从源码看,启用 LDAP 的设置 ldap-enabled 在 setter 中会先执行一次连接测试 settings.clj:
;; Test the LDAP settings before enabling
(let [result ((requiring-resolve 'metabase.sso.ldap/test-current-ldap-details))]
(when-not (= :SUCCESS (:status result))
(throw (ex-info (tru "Unable to connect to LDAP server with current settings")
((requiring-resolve 'metabase.sso.ldap/humanize-error-messages) result)))))
即:连接不成功,LDAP 就根本不会被启用,并会把底层异常翻译成可读错误返回给界面。这意味着"配置 LDAP 时表单立刻报错"本身就是第一道排障信号——错误文案直接指出了问题所在。
连接测试做了什么
test-ldap-connection 的实现位于 ldap.clj,它做两件事:
- 用当前 host / port / bind-dn / password / security 建立连接;
- 对
user-base(以及非空的group-base)执行ldap/get,确认搜索起点真实存在且可读。
任何一步失败都会返回 {:status :ERROR, :message ...}。因此"user search base 不存在或不可读"、"group search base 不存在或不可读"是配置阶段最常见的两类报错。
三、MB_LDAP_* 环境变量完整参考
上文的 docker-compose 通过环境变量注入配置,这正是 环境变量文档 中登记的 MB_LDAP_* 系列变量。全部变量及默认值整理如下(对应配置文件写法见 config-file.md):
| 环境变量 | 类型 | 默认值 | 说明 |
|---|---|---|---|
MB_LDAP_ENABLED |
boolean | false |
是否启用 LDAP 认证 |
MB_LDAP_HOST |
string | null |
LDAP 服务器主机名 |
MB_LDAP_PORT |
integer | 389 |
服务器端口,SSL 时通常为 636 |
MB_LDAP_SECURITY |
keyword | none |
加密方式:none / ssl / starttls |
MB_LDAP_BIND_DN |
string | null |
绑定 DN,用于查询其他用户信息 |
MB_LDAP_PASSWORD |
string | null |
绑定密码 |
MB_LDAP_USER_BASE |
string | null |
用户搜索起点(递归搜索) |
MB_LDAP_USER_FILTER |
string | (&(objectClass=inetOrgPerson)(|(uid={login})(mail={login}))) |
用户查找过滤器,{login} 会被替换为用户输入 |
MB_LDAP_ATTRIBUTE_EMAIL |
string | mail |
映射为邮箱的 LDAP 属性(常见 mail / email / userPrincipalName) |
MB_LDAP_ATTRIBUTE_FIRSTNAME |
string | givenName |
映射为名字的 LDAP 属性 |
MB_LDAP_ATTRIBUTE_LASTNAME |
string | sn |
映射为姓氏的 LDAP 属性 |
MB_LDAP_GROUP_SYNC |
boolean | false |
是否启用 LDAP 组同步 |
MB_LDAP_GROUP_BASE |
string | null |
组搜索起点;提供 memberOf overlay 的目录(如 Active Directory)可留空 |
MB_LDAP_GROUP_MAPPINGS |
json | {} |
LDAP 组 DN 到 Metabase 组 ID 的映射 JSON |
MB_LDAP_GROUP_MEMBERSHIP_FILTER |
string | (member={dn}) |
组成员查找过滤器,{dn} 与 {uid} 会被替换为用户 DN 与 UID |
MB_LDAP_SYNC_USER_ATTRIBUTES |
boolean | true |
用户通过 LDAP 登录时是否同步用户属性 |
MB_LDAP_SYNC_USER_ATTRIBUTES_ALLOWLIST |
csv | ``(空) | 仅同步列表中列出的属性;留空表示不同步任何属性 |
MB_LDAP_SYNC_USER_ATTRIBUTES_BLACKLIST |
csv | userPassword,dn,distinguishedName |
跳过不同步的属性列表 |
MB_LDAP_TIMEOUT_SECONDS |
double | 15.0 |
等待 LDAP 服务器的最大秒数,超时后回落到本地认证 |
MB_LDAP_TRUST_STORE |
string | null |
用于校验 LDAP 服务器 TLS 证书的 JKS 信任库路径;留空使用 JVM 默认信任库 |
这些设置全部在 settings.clj 中以 defsetting 形式定义,其中若干细节值得排障时留意:
- 属性映射默认值:email 默认取
mail,first name 默认取givenName,last name 默认取sn。若你的目录用其他属性承载这些信息,必须显式配置,否则用户登录后姓名会落为默认值 "Unknown",邮箱缺失则无法创建账号也无法登录(详见 LDAP 配置指南)。 MB_LDAP_TIMEOUT_SECONDS:源码中该超时同时约束了find-user与verify-password两步(见 ldap.clj 与 ldap.clj)。当 LDAP 服务器响应缓慢时,登录会表现为"长时间卡顿后回落到本地认证",此时应调大该值或检查网络链路。MB_LDAP_TRUST_STORE:与 TLS 校验相关,见下文第四节。
四、SSL / StartTLS 连接与证书信任链
排障时最容易忽略的是加密方式与证书校验。源码中的连接层 ldap.clj 揭示了三条路径:
none(明文):端口默认389,走 clj-ldap 的普通连接;ssl(LDAPS):端口默认636,直接用信任库创建 SSL 连接;starttls:先在明文连接上发起StartTLSExtendedRequest升级到 TLS,再完成绑定。
无论 SSL 还是 StartTLS,Metabase 都会做两层校验:
- 证书链校验:使用操作员配置的
ldap-trust-store(MB_LDAP_TRUST_STORE,JKS 格式);留空则回落到 JVM 默认信任库($JAVA_HOME/lib/security/cacerts,或javax.net.ssl.trustStore系统属性指定的路径); - 主机名校验:连接选项上设置了
HostNameSSLSocketVerifier,确保证书中的主机名与所连 host 一致(ldap.clj)。
因此,当报错涉及 SSL 时,排障顺序通常是:确认端口是 636(SSL)还是 389+StartTLS → 确认服务器证书由受信 CA 签发或已导入自定义 JKS 信任库 → 确认证书 CN/SAN 与 MB_LDAP_HOST 一致。若只是想先连通自签名证书的测试环境,可通过 MB_LDAP_TRUST_STORE 指向包含该证书的 JKS 文件解决。
五、登录失败时:源码级错误码对照表
当 LDAP 已启用但用户登录仍失败时,Metabase 会把底层异常翻译为可读提示。翻译逻辑集中在 humanize-error-messages(ldap.clj),它按正则匹配异常消息并映射到具体配置字段。下表是排障时最实用的"错误 → 根因"对照:
| 异常消息特征 | 界面提示字段 | 根因 |
|---|---|---|
UnknownHostException / ConnectException |
ldap-host、ldap-port |
主机或端口错误,无法建立 TCP 连接 |
SocketException / SSLException |
ldap-port、ldap-security |
端口与加密方式不匹配(如用明文端口访问 SSL 服务) |
^For input string.* |
ldap-host |
host 中误带了 ldap:// 或 ldaps:// 前缀,导致端口解析失败 |
password was incorrect |
ldap-password |
绑定密码错误 |
Unable to bind as user / 解析 bind DN 失败 |
ldap-bind-dn |
bind DN 错误或格式非法 |
Active Directory data 525 |
ldap-bind-dn |
用户不存在(AD 特有错误码) |
Active Directory data 52e |
ldap-bind-dn、ldap-password |
用户名或密码错误 |
Active Directory data 532 |
ldap-password |
密码已过期 |
Active Directory data 533 |
ldap-bind-dn |
账号被禁用 |
Active Directory data 701 |
ldap-bind-dn |
账号已过期 |
User search base does not exist |
ldap-user-base |
用户搜索基点不存在或不可读 |
Group search base does not exist |
ldap-group-base |
组搜索基点不存在或不可读 |
尤其注意 Active Directory 的 data 5xx 系列错误码:它们是 Windows 域控制器在绑定阶段返回的细分状态,Metabase 借此能区分"密码过期"(532)、"账号禁用"(533)、"账号过期"(701)等不同情形,让运维可以直接把界面提示转达给目录管理员处理。
认证链路的完整时序
结合 providers/ldap.clj 与 default_implementation.clj,一次 LDAP 登录的内部流程为:
- 用当前 LDAP 设置建立连接池(
with-ldap-connection); - 以
{login}替换后的用户过滤器在user-base下执行递归子树搜索(scope :sub、size-limit 1),命中即取得用户的 DN、email、姓名等属性; - 用该 DN 与用户输入的密码执行
ldap/bind?二次绑定,验证口令(受ldap-timeout-seconds超时约束); - 认证通过后,若开启了组同步,再依据组映射把 LDAP 组 DN 翻译为 Metabase 组 ID 并同步成员关系(
ldap-groups->mb-group-ids,见 default_implementation.clj),成员变更在用户重新登录后生效。
因此,排障时可以按"搜索命中 → 密码验证 → 组同步"三个阶段逐段观察日志:Searching for LDAP user with user search base ...、LDAP search returned N result(s) 等调试日志会打印在服务端日志中(对应 default_implementation.clj)。如果搜索返回 0 条,问题几乎必在 user-base 或 user-filter;如果搜索命中但提示密码错误,问题在 bind DN 与用户口令。
六、组同步与用户属性同步(进阶排障点)
组映射的配置在 Group Schema 区域:开启组映射后,用 "Edit Mapping" 把 LDAP 组 DN(如 cn=Accounting,ou=Groups,dc=widgetco,dc=com)关联到 Metabase 已有组。三个行为要点(源自 LDAP 配置指南):
- Administrator 组与其他组行为一致,同样可被映射;
- 组成员关系变更不是即时生效的,用户重新登录后才会同步;
- 同步只增删已建立映射的组,未映射的 Metabase 组不受影响。
组数据的来源有两种:优先读取 LDAP 返回的 memberOf overlay 属性(Active Directory、FreeIPA 等自带);否则回退为在 group-base 下执行组成员过滤器查询(默认 (member={dn})),见 default_implementation.clj。如果目录两者都不支持,组的获取结果为空数组,此时应检查 MB_LDAP_GROUP_BASE 与 MB_LDAP_GROUP_MEMBERSHIP_FILTER 的配置。
用户属性同步则受 MB_LDAP_SYNC_USER_ATTRIBUTES、MB_LDAP_SYNC_USER_ATTRIBUTES_ALLOWLIST、MB_LDAP_SYNC_USER_ATTRIBUTES_BLACKLIST 三个变量控制,属性的使用场景是行级/列级权限(row-and-column-security.md)。
七、已知限制:MySQL 应用库 + 二进制字段同步问题
官方文档明确记录了一个针对企业版(Enterprise)环境的重要限制:
当 Metabase Enterprise 搭配 MySQL 应用数据库并启用 LDAP 时,务必通过
MB_LDAP_SYNC_USER_ATTRIBUTES_BLACKLIST环境变量禁用从 LDAP 目录同步二进制字段。否则可能触及 MySQL 文本字段 60K 大小上限,导致无法创建用户,或已存在的用户无法登录。
背景是:LDAP 目录中的某些属性(如照片、证书等)是二进制大对象,若被当作用户属性同步进应用库的文本列,数据量会超出 MySQL TEXT 类型约 64KB 的存储上限。该变量的默认值为 userPassword,dn,distinguishedName(见 环境变量文档),即默认已跳过这三类高敏/易超限属性;一旦你的目录中还存在其他二进制属性,就需要将其 DN 名称追加进黑名单。若未配置而已经触发 60K 错误,排查方向应是清点目录中所有二进制属性并全部加入黑名单。
八、排障工具链与进一步资源
使用 Apache Directory Studio 独立验证目录
文档推荐使用 Apache Directory Studio 这类 LDAP 客户端独立排查:
- 用它登录同一套 LDAP 目录(填同样的 host / port / bind DN / 密码),验证账号凭据本身是否可用,把"Metabase 配置问题"与"目录/账号问题"解耦;
- 它可以直接浏览整个 LDAP 树,检查用户是否真的存在于
user-base之下、对象类是否为inetOrgPerson、uid/mail/givenName/sn等属性是否已填充; - 它还能查看 LDAP 服务器日志,观察 Metabase 实际发出的查询,从而确认
user-filter与group-membership-filter是否按预期执行。
常见问题速查
- 保存配置报 "User search base does not exist":核对
MB_LDAP_USER_BASEDN 是否真实存在且对 bind 用户可读,可在 Apache Directory Studio 中浏览确认; - 能配置但登录失败:检查
user-filter是否过度收窄(如删除了(mail={login})分支但用户习惯用邮箱登录)、用户密码是否过期/账号是否禁用(对照第五节 AD 错误码表); - 登录卡顿后回落到本地认证:检查
MB_LDAP_TIMEOUT_SECONDS与网络链路; - SSL 报错:按第四节核对端口、加密方式、信任库与证书主机名;
- MySQL + LDAP 下用户创建失败:按第七节处理二进制属性同步黑名单。
相关文档
- Metabase LDAP 配置指南:启用步骤、必填属性、组映射完整说明
- 无法登录通用排查:非 LDAP 特定问题的登录排查
- 已知问题与限制:查阅历史 known bugs
- 环境变量完整参考:全部
MB_LDAP_*变量 - 配置文件方式:以
ldap-*键名写入配置文件 - 行级/列级权限与用户属性:用户属性的下游使用场景
- 权限总览:组与权限的关联管理
如需深入源码验证行为,可重点阅读 sso/ldap.clj(连接、测试与错误翻译)、sso/settings.clj(全部设置定义与默认值)、sso/ldap/default_implementation.clj(用户查找与组解析)、sso/api/ldap.clj(REST 配置接口)。