MongoDB企业版支持将身份认证委托给外部LDAP目录服务，社区版不包含该能力。启用LDAP认证后，客户端提交的用户名和密码不会与本地SCRAM凭据比对，而是转发到LDAP服务器进行绑定校验。这种模式让数据库账号跟随企业统一目录走，员工离职或调岗时，管理员只需在LDAP中禁用账户，MongoDB的访问入口即刻失效，不再出现清理本地账号遗漏的问题。实现方式可以分成两条技术路线：借助操作系统PAM模块和saslauthd间接连接LDAP，或者使用MongoDB原生LDAP认证直接查询目录。前者复用系统层认证栈，适合已经部署pam_ldap的环境；后者配置集中、不依赖本地LDAP客户端，跨平台行为更一致。
一、原生LDAP认证与saslauthd方案的取舍
MongoDB官方文档将LDAP集成划分为两条路径。saslauthd方案通过操作系统的SASL守护进程转发认证请求，MongoDB只需要配置authenticationMechanisms为PLAIN，并在mongod或mongos节点上启用saslServiceName和saslauthd相关参数。此时用户名会从MongoDB传递到saslauthd，再交给pam_ldap或nss_ldap完成实际目录校验。优点是可以复用成熟的系统PAM配置，比如SSH、sudo已经接入LDAP的环境可以直接共享认证策略。缺点也很明显：每个数据库节点都要安装并维护saslauthd、libpam-ldap等组件，排查问题需要同时查看MongoDB日志和操作系统认证日志，链路更长。
原生LDAP认证是MongoDB企业版在3.4版本引入的能力，它让mongod直接通过LDAP协议连接目录服务器。配置集中在security.ldap段落，不需要操作系统额外安装PAM组件。认证时MongoDB先使用查询凭证在LDAP中搜索用户DN，再以该DN和客户端提供的密码发起绑定。这种方式的优势是部署简单、行为一致，尤其在容器或不可变主机环境中，少了系统组件依赖会省去很多初始化步骤。不过它要求MongoDB版本为企业版，且LDAP服务器网络必须对每个mongod可达。
从运维角度比较，如果团队已经维护了完整的PAM/LDAP体系，saslauthd方案可以快速落地；如果是全新建设，或者MongoDB集群节点分散在不同操作系统上，优先选择原生LDAP认证，避免在每台机器上调试PAM模块版本和配置文件差异。生产环境建议统一走原生LDAP，因为配置项明确、审计范围更小。
二、MongoDB原生LDAP认证关键配置解析
原生LDAP认证的配置入口在/etc/mongod.conf的security段。首先要开启授权，然后指定LDAP服务器地址。服务器地址支持逗号分隔多个LDAP主机，MongoDB会按顺序尝试连接。下面是一个完整的配置片段：
security:
authorization: enabled
ldap:
servers: "ldap1.ipipp.com,ldap2.ipipp.com"
bind:
queryUser: "cn=mongodb-bind,ou=service,dc=example,dc=com"
queryPassword: "change-me"
userToDNMapping:
- match: "(.+)"
substitution: "uid={0},ou=people,dc=example,dc=com"
authz:
queryTemplate: "dc=example,dc=com??sub?(&(uid={USER})(memberOf=cn=mongodb-users,ou=groups,dc=example,dc=com))"
transportSecurity: tls
这里servers列出LDAP服务器，多个地址之间不要有空格。bind.queryUser是MongoDB用于搜索目录的专用账号，它不应是普通用户账号，而应具备读取用户和组成员属性的权限。bind.queryPassword建议使用MongoDB的配置加密或文件权限保护，不要直接放在版本控制里。userToDNMapping负责把客户端提交的用户名转换成完整的DN，下一节会详细说明。
authz.queryTemplate用来在认证完成后进一步验证用户是否符合访问条件。模板格式为baseDN??scope?filter，中间两个问号表示使用默认搜索基址，第三个问号后是LDAP过滤器。过滤器中的{USER}占位符会被替换成客户端用户名，但替换前会做LDAP转义，避免特殊字符注入。只有该查询返回至少一条记录时，认证才会成功。这个查询并非替代MongoDB角色授权，而是作为进入数据库前的最后一道目录级校验。
transportSecurity可以设置为tls或none。生产环境必须使用TLS，否则LDAP查询和绑定密码会在网络上明文传输。开启TLS后，还要通过security.ldap.server.ca等参数指定CA证书，确保证书链可信。若使用自建CA，需要把根证书分发到每个mongod节点。
三、userToDNMapping的三种模式与转义规则
用户名到DN的映射是LDAP集成中最容易出错的一环。MongoDB为userToDNMapping提供了三种处理模式。第一种是替换模式，使用match正则表达式和substitution模板。上面的配置中，(.+)捕获任意非空用户名，{0}引用完整匹配结果，于是alice会被转换为uid=alice,ou=people,dc=example,dc=com。替换模式实现简单，但要求所有用户在同一个OU下，且uid与MongoDB登录名完全一致。
第二种是LDAP查询模式，使用match加ldapQuery。它先验证用户名是否符合正则，再以该用户名作为过滤条件执行LDAP搜索。配置示例：
security:
ldap:
userToDNMapping:
- match: "(.+)"
ldapQuery: "ou=people,dc=example,dc=com??sub?(&(uid={0})(objectClass=inetOrgPerson))"
这种方式适合DN不在同一层级、或者uid与DN中命名属性不完全一致的情况。LDAP服务器返回完整DN，MongoDB拿它进行绑定。查询模板中的{0}会被正则捕获组替换，同样自动做LDAP过滤转义。如果用户名中含有星号、括号等LDAP敏感字符，不用担心查询被破坏。
第三种是直接指定DN模板，可以在userToDNMapping中写死固定前缀和后缀，但灵活性最差，实际很少使用。需要提醒的是，match配置为正则时，MongoDB使用PCRE语法，捕获组从{0}开始编号。多个映射规则按数组顺序匹配，第一条成功即停止；如果没有规则命中，认证直接失败。
转义是安全边界。MongoDB会自动对进入LDAP过滤器的用户名转义，但如果管理员在substitution或ldapQuery中拼接了来自外部配置的其他变量，仍需自行确保这些值不破坏LDAP语义。建议把userToDNMapping写成一个规则，不要堆叠复杂正则，保持可读性。
四、创建外部用户并完成角色授权
LDAP只负责验证身份，MongoDB的授权仍然基于自身角色体系。因此开启LDAP认证后，还需要在$external数据库里为用户创建对应的外部身份记录。例如alice已经能通过LDAP认证，但没有MongoDB用户记录就会报错。管理员需要执行：
db.getSiblingDB("$external").createUser(
{
user: "alice",
roles: [
{ role: "readWrite", db: "sales" },
{ role: "read", db: "reporting" }
]
}
)
这里的user字段必须与客户端登录使用的用户名完全一致，也必须是userToDNMapping转换前或查询模板中期望的用户名。创建完成后，客户端可以通过mongosh --username alice --password 密码 --authenticationDatabase '$external' --authenticationMechanism PLAIN连接。注意认证数据库固定为$external，机制为PLAIN，因为MongoDB需要通过LDAP绑定传递明文密码。
如果有大量用户需要从LDAP同步角色，可以编写脚本遍历LDAP中的组成员，调用createUser或updateUser批量维护。LDAP组本身不会被自动映射成MongoDB角色，authz.queryTemplate只是判断目录中有没有符合条件的记录。角色管理的自动化要借助外部工具，例如定时读取LDAP组成员变化，再用脚本更新MongoDB权限。这一步决定权限回收能否跟上组织调整，不能省略。
五、连接测试与排错要点
完成配置后先重启mongod，查看日志确认LDAP相关参数加载成功。测试阶段建议在命令行显式指定认证数据库和机制：
mongosh "mongodb://alice:secret@mongodb1.ipipp.com:27017/sales?authSource=%24external&authMechanism=PLAIN"
这条连接串中的%24是美元符号的URL编码，对应$external。如果认证失败，先确认LDAP服务器是否允许来自MongoDB节点的查询。可以使用ldapsearch以和bind.queryUser相同的凭证执行一次搜索，验证目录连通性和权限。
ldapsearch -x -H ldaps://ldap1.ipipp.com \ -D "cn=mongodb-bind,ou=service,dc=example,dc=com" \ -W -b "ou=people,dc=example,dc=com" \ "(uid=alice)" dn
MongoDB日志中常见的错误包括LDAP server unavailable、failed to authenticate user、connection timeout。遇到超时要检查防火墙、DNS解析和servers地址的可达性。TLS握手失败则要核对CA证书路径和LDAP服务器证书中的主机名是否与配置一致。如果出现bind失败，确认查询账号密码正确且未过期，必要时在LDAP端开启审计查看绑定来源。
另一个容易被忽略的点是userToDNMapping中的正则不匹配导致所有用户都无法认证。此时可以把规则先简化成(.+)加固定替换模板，确认链路打通后再逐步收紧。也可以在mongod配置中临时设置更高级别日志，观察MongoDB实际构造的DN和过滤器参数，定位是映射错误还是目录数据缺失。
MongoDB LDAP认证LDAP集成认证userToDNMapping修改时间：2026-09-28 13:54:36