mongoldap
MongoDB Enterprise
Synopsis
MongoDB Enterprise提供 mongoldap
,用于针对运行的LDAP服务器或服务器设立测试 MongoDB 的LDAP 配置选项。
要验证配置文件中的 LDAP 选项,请将mongoldap
--config
选项设置为配置文件的路径。
要测试 LDAP 配置选项,您必须指定--user
和--password
。 mongoldap
模拟对使用所提供的配置选项和档案运行的 MongoDB 服务器进行身份验证。
mongoldap
返回一份报告,其中包括 LDAP 身份验证或授权过程中任何步骤的成功或失败。 错误消息包括遇到的特定错误的信息以及解决错误的潜在建议。
配置与LDAP 授权相关的选项时, mongoldap
会执行使用提供的配置选项和用户名构建的 LDAP 查询,并返回admin
数据库中用户已获得授权的角色列表。
在配置LDAP 授权角色以进行用户访问控制时,可以使用此信息。 例如,使用mongoldap
确保您的配置允许特权用户获得执行其预期任务所需的角色。 同样,使用mongoldap
确保您的配置禁止非特权用户获取用于访问 MongoDB Server 的角色或执行未经授权的操作。
配置与LDAP 身份验证相关的选项时,请使用mongoldap
以确保身份验证操作按预期运行。
安装
mongoldap
工具是MongoDB database Tools Extra包的一部分,可以与MongoDB Server一起安装,也可以独立安装。
使用MongoDB Server进行安装
要在安装mongoldap
MongoDB EnterpriseMongoDB Server时安装 :
请按照适用于您平台的说明进行操作:安装MongoDB Enterprise MongoDB Server
完成安装后,您可以在与 相同的位置找到
mongoldap
和其他包含的工具。MongoDB Server注意
对于 Windows
.msi
安装程序向导, Complete安装选项包括mongoldap
。
独立安装
要将mongoldap
作为独立安装进行安装:
点击MongoDB Enterprise的下载链接: MongoDB Enterprise下载中心
从下拉菜单中选择您的Platform (操作系统),然后根据下表选择适合您平台的Package :
OS安装包Linuxtgz
安装包Windowszip
安装包macOStgz
安装包下载后,解压缩存档并将
mongoldap
复制到硬盘上的某个位置。
使用
注意
LDAP 或 Active Directory 的完整描述超出了本文档的范围。
请考虑以下示例配置文件,该文件旨在支持通过 Active 目录进行 LDAP 身份验证和授权:
security: authorization: "enabled" ldap: servers: "activedirectory.example.net" bind: queryUser: "mongodbadmin@dba.example.com" queryPassword: "secret123" userToDNMapping: '[ { match : "(.+)", ldapQuery: "DC=example,DC=com??sub?(userPrincipalName={0})" } ]' authz: queryTemplate: "DC=example,DC=com??sub?(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={USER}))" setParameter: authenticationMechanisms: "PLAIN"
您可以使用mongoldap
验证配置文件,该文件会返回该过程的报告。 您必须为mongoldap
指定用户名和密码。
mongoldap --config=<path-to-config> --user="bob@dba.example.com" --password="secret123"
如果提供的档案有效,并且配置文件中的 LDAP 选项有效,则输出可能如下:
Checking that an LDAP server has been specified... [OK] LDAP server found Connecting to LDAP server... [OK] Connected to LDAP server Parsing MongoDB to LDAP DN mappings.. [OK] MongoDB to LDAP DN mappings appear to be valid Attempting to authenticate against the LDAP server... [OK] Successful authentication performed Checking if LDAP authorization has been enabled by configuration... [OK] LDAP authorization enabled Parsing LDAP query template.. [OK] LDAP query configuration template appears valid Executing query against LDAP server... [OK] Successfully acquired the following roles: ...
行为
从 MongoDB 5.1 开始, mongoldap
支持在 LDAP 服务器上使用srv:
和srv_raw:
作为前缀。
如果您的连接字符串指定"srv:<DNS_NAME>"
, mongoldap
将验证"_ldap._tcp.gc._msdcs.<DNS_NAME>"
是否存在,以便 SRV 支持 Active 目录。 如果未找到, mongoldap
将验证 SRV 是否存在"_ldap._tcp.<DNS_NAME>"
。 如果找不到 SRV 记录, mongoldap
会警告您使用"srv_raw:<DNS_NAME>"
。
如果连接字符串指定"srv_raw:<DNS_NAME>"
,则mongoldap
会查找"<DNS NAME>"
的 SRV 记录。
选项
--config=<filename>, -f=<filename>
指定运行时配置选项的配置文件。 这些选项相当于命令行配置选项。 有关更多信息,请参阅自管理配置文件选项。
mongoldap
使用与自 管理部署上的LDAP 管理LDAP代理身份验证 或 LDAP 授权相关的任何配置选项来测试LDAP身份验证或授权。需要指定
--user
。 可以接受--password
来测试 LDAP 身份验证。确保配置文件使用 ASCII 编码。
mongoldap
实例不支持采用非 ASCII 编码(包括 UTF- 8的配置文件。
--user=<string>
mongoldap
尝试 LDAP 身份验证或授权时使用的用户名。
--ldapServers=<host1>:<port>,<host2>:<port>,...,<hostN>:<port>
LDAP 服务器,
mongoldap
在该服务器上对用户进行身份验证或确定授权用户可对给定数据库执行哪些操作。 如果指定的 LDAP 服务器有任何复制实例,则可以在以逗号分隔的列表中指定每个复制服务器的主机和端口。如果您的 LDAP 基础架构将 LDAP 目录分区到多个 LDAP 服务器,请将一个LDAP 服务器或其任何复制实例指定为
--ldapServers
。 MongoDB 支持 RFC45114.1 中定义的以下 LDAP10 引用。 。请勿使用--ldapServers
列出基础架构中的每台 LDAP 服务器。如果未设置,
mongoldap
将无法使用LDAP 身份验证或授权。
--ldapQueryUser=<string>
仅在 MongoDB Enterprise 中可用。
连接到 LDAP 服务器或在该服务器上执行查询时,
mongoldap
绑定的身份。仅当满足以下任一条件时才需要:
使用 LDAP 授权。
将 LDAP 查询用于
username transformation
LDAP 服务器不允许匿名绑定
您必须使用
--ldapQueryUser
和--ldapQueryPassword
。如果未设置,
mongoldap
将不会尝试绑定到 LDAP 服务器。注意
Windows MongoDB 部署可以使用
--ldapBindWithOSDefaults
而不是--ldapQueryUser
和--ldapQueryPassword
。不能同时指定--ldapQueryUser
和--ldapBindWithOSDefaults
。
仅在 MongoDB Enterprise 中可用。
使用 --ldapQueryUser
时用于绑定到 LDAP 服务器的密码。您必须使用 --ldapQueryPassword
与 --ldapQueryUser
。
如果未设置,则 mongoldap
不会尝试绑定到 LDAP 服务器。
您可以使用 setParameter
在运行中的 mongoldap
配置此设置。
ldapQueryPassword
setParameter
命令接受string或字符串数组。 如果将ldapQueryPassword
设置为数组,则 MongoDB 按顺序尝试每个密码,直到成功为止。 使用密码数组滚动 LDAP 帐户密码,无需停机。
注意
Windows MongoDB 部署可以使用 --ldapBindWithOSDefaults
而不是 --ldapQueryUser
和 --ldapQueryPassword
。不能同时指定 --ldapQueryPassword
和 --ldapBindWithOSDefaults
。
--ldapBindWithOSDefaults=<bool>
默认:false
仅在 Windows 平台上的 MongoDB Enterprise 中可用。
在连接到 LDAP 服务器时,允许
mongoldap
使用您的 Windows 登录档案进行身份验证或绑定。仅在以下情况下才需要:
使用 LDAP 授权。
将 LDAP 查询用于
username transformation
LDAP 服务器不允许匿名绑定
使用
--ldapBindWithOSDefaults
替换--ldapQueryUser
和--ldapQueryPassword
。
--ldapBindMethod=<string>
默认值:简单
仅在 MongoDB Enterprise 中可用。
方法
mongoldap
用于向 LDAP 服务器进行身份验证。 与--ldapQueryUser
和--ldapQueryPassword
一起使用,连接到 LDAP 服务器。--ldapBindMethod
支持以下值:如果指定
sasl
,则可以使用--ldapBindSaslMechanisms
配置可用的 SASL 机制。mongoldap
默认使用DIGEST-MD5
机制。
--ldapBindSaslMechanisms=<string>
默认值:DIGEST-MD5
仅在 MongoDB Enterprise 中可用。
以逗号分隔的 SASL 机制列表,
mongoldap
可在向 LDAP 服务器进行身份验证时使用。mongoldap
和 LDAP 服务器必须就至少一种机制达成一致。mongoldap
在运行时动态加载主机上安装的任何 SASL 机制库。在
mongoldap
主机和远程 LDAP 服务器主机上为所选 SASL 机制安装和配置相应的库。 您的操作系统可能默认包含某些 SASL 库。 请参阅与每个 SASL 机制相关的文档以获取安装和配置指南。如果将
GSSAPI
SASL 机制与自托管部署上的Kerberos身份验证结合使用,请验证mongoldap
托管的以下内容:Linux
KRB5_CLIENT_KTNAME
环境变量会解析为主机客户端 Linux Keytab 文件的名称。有关 Kerberos 环境变量的更多信息,请参阅 Kerberos 文档。客户端密钥表包含供
mongoldap
连接到 LDAP 服务器并执行 LDAP 查询时使用的 用户主体 。
Windows
- 如果连接到 Active Directory 服务器,Windows Kerberos 配置会自动生成 Ticket-Granting-Ticket 当用户登录系统时。将
--ldapBindWithOSDefaults
设置为true
,以允许mongoldap
在连接到 Active Directory 服务器时使用生成的档案并执行查询。
将
--ldapBindMethod
设置为sasl
以使用此选项。注意
有关 SASL 机制的完整列表,请参阅 IANA 列表。请参阅 LDAP 或 Active Directory 服务的文档来识别与该服务兼容的 SASL 机制。
MongoDB 不是 SASL 机制库的来源,MongoDB 文档也不是安装或配置任何给定 SASL 机制的权威来源。如需获得文档和支持,请咨询 SASL 机制库供应商或所有者。
有关 SASL 的更多信息,请参阅以下资源:
对于 Linux,请参阅 Cyrus SASL 文档。
对于 Windows,请参阅 Windows SASL 文档。
--ldapTransportSecurity=<string>
默认值:tls
仅在 MongoDB Enterprise 中可用。
默认情况下,
mongoldap
会创建与 LDAP 服务器的 TLS/SSL 安全连接。对于 Linux 部署,必须在
/etc/openldap/ldap.conf
文件中配置相应的 TLS 选项。操作系统的程序包管理器通过libldap
依赖项创建此文件作为 MongoDB Enterprise 安装的一部分。有关更完整的说明,请参阅 ldap.conf OpenLDAP 文档中的TLS Options
。在 Windows 上部署时,必须将 LDAP 服务器 CA 证书添加到 Windows 证书管理工具中。该工具的确切名称和功能可能会因操作系统版本而异。有关证书管理的更多信息,请参阅您的 Windows 版本对应的文档。
将
--ldapTransportSecurity
设置为none
,以禁用mongoldap
和 LDAP 服务器之间的 TLS/SSL。警告
将
--ldapTransportSecurity
设置为none
可在mongoldap
和 LDAP 服务器之间传输纯文本信息,可能还传输凭证。
--ldapTimeoutMS=<int>
默认值:10000
仅在 MongoDB Enterprise 中可用。
等待 LDAP 服务器响应请求的时间(以毫秒
mongoldap
为单位)。如果失败的根源是连接超时,增加
--ldapTimeoutMS
的值可以防止 MongoDB 服务器和 LDAP 服务器之间的连接失败。降低--ldapTimeoutMS
的值会缩短 MongoDB 等待 LDAP 服务器响应的时间。
--ldapUserToDNMapping=<string>
仅在 MongoDB Enterprise 中可用。
将提供给
mongoldap
进行身份验证的用户名映射到 LDAP 标识名 (DN)。 在以下情况下,您可能需要使用--ldapUserToDNMapping
将用户名转换为 LDAP DN:通过 LDAP 简单绑定进行 LDAP 身份验证,其中用户使用非完整 LDAP DN 的用户名向 MongoDB 进行身份验证。
使用需要 DN 的
LDAP authorization query template
。使用不同的身份验证机制(如 x.509、kerberos)将向 Mongo DB 进行身份验证的客户端的用户名转换为完整的 LDAP DN,以进行授权。
--ldapUserToDNMapping
需要一个用引号括住的 JSON 字符串,代表一个有序的文档数组。每个文档都包含正则表达式match
以及用于转换传入用户名的substitution
或ldapQuery
模板。数组中的每个文档均采用以下形式:
{ match: "<regex>" substitution: "<LDAP DN>" | ldapQuery: "<LDAP Query>" } 字段说明例子match
ECMAScript 格式的正则表达式 (regex),用于与提供的用户名进行匹配。每个括号括起来的部分表示substitution
或ldapQuery
使用的正则表达式捕获组。"(.+)ENGINEERING"
"(.+)DBA"
substitution
"cn={0},ou=engineering, dc=example,dc=com"
ldapQuery
"ou=engineering,dc=example, dc=com??one?(user={0})"
对于数组中的每个文档,必须使用
substitution
或ldapQuery
。不能在同一文档中同时指定两者。执行身份验证或授权时,
mongoldap
会按给定顺序遍历数组中的每个文档,对照match
筛选器检查身份验证用户名。 如果找到匹配项,mongoldap
则会应用转换并使用输出对用户进行身份验证。mongoldap
不检查数组中的其余文档。如果给定文档与提供的身份验证名称不匹配,
mongoldap
会继续浏览文档列表以查找其他匹配项。 如果在任何文档中均未找到匹配项,或者文档描述的转换失败,mongoldap
将返回错误。如果由于 LDAP 服务器的网络或身份验证失败而无法评估其中一项转换,
mongoldap
也会返回错误。mongoldap
会拒绝连接请求,并且不检查数组中的其余文档。从 MongoDB 5.0 开始,
--ldapUserToDNMapping
接受空字符串""
或空数组[ ]
来代替映射文档。如果--ldapUserToDNMapping
提供空字符串或空数组,MongoDB 会将经过身份验证的用户名映射为 LDAP DN。以前,提供空映射文档会导致映射失败。例子
下面展示了两个转换文档。第一个文档匹配以
@ENGINEERING
结尾的任何字符串,将后缀前面的所有内容放入正则表达式捕获组中。第二个文档匹配以@DBA
结尾的任何字符串,将后缀前面的所有内容放入正则表达式捕获组中。重要
必须将数组作为字符串传递给 --ldapUserToDNMapping。
"[ { match: "(.+)@ENGINEERING.EXAMPLE.COM", substitution: "cn={0},ou=engineering,dc=example,dc=com" }, { match: "(.+)@DBA.EXAMPLE.COM", ldapQuery: "ou=dba,dc=example,dc=com??one?(user={0})" } ]" 用户名为
alice@ENGINEERING.EXAMPLE.COM
的用户匹配第一个文档。正则表达式捕获群组{0}
对应于字符串alice
。生成的输出是 DN"cn=alice,ou=engineering,dc=example,dc=com"
。用户名为
bob@DBA.EXAMPLE.COM
的用户匹配第二个文档。 正则表达式捕获群组{0}
对应于stringbob
。 生成的输出是 LDAP 查询"ou=dba,dc=example,dc=com??one?(user=bob)"
。mongoldap
针对 LDAP 服务器执行此查询,并返回结果"cn=bob,ou=dba,dc=example,dc=com"
。如果未设置
--ldapUserToDNMapping
,则mongoldap
在尝试根据 LDAP 服务器对用户进行身份验证或授权时,不会对用户名进行任何转换。
--ldapAuthzQueryTemplate=<string>
仅在 MongoDB Enterprise 中可用。
格式符合 RFC4515 的相对 LDAP 查询 URL 和 RFC4516
mongoldap
执行此命令以获取经过身份验证的用户所属的 LDAP 群组。该查询相对于--ldapServers
中指定的一个或多个主机。在 URL 中,可以使用以下替换令牌:
替换令牌说明{USER}
使用经过身份验证的用户名进行替换,或者,如果指定了username mapping
,则使用transformed
用户名进行替换。{PROVIDED_USER}
替换提供的用户名,即在身份验证或LDAP transformation
之前。构造查询 URL 时,请确保 LDAP 参数的顺序遵循 RFC4516:
[ dn [ ? [attributes] [ ? [scope] [ ? [filter] [ ? [Extensions] ] ] ] ] ] 如果您的查询包含属性,则
mongoldap
假定该查询检索该实体所属的 DN。如果查询不包含属性,则
mongoldap
假定该查询检索用户所属的所有实体。对于查询返回的每个 LDAP DN,
mongoldap
都会在admin
数据库中为授权用户分配相应的角色。 如果admin
数据库上的角色与 DN 完全匹配,mongoldap
将向用户授予该角色以及分配给该角色的权限。 有关创建角色的更多信息,请参阅db.createRole()
方法。例子
此 LDAP 查询返回 LDAP 用户对象的
memberOf
属性中列出的所有群组。"{USER}?memberOf?base" 您的 LDAP 配置可能不包含
memberOf
属性作为用户架构的一部分,可能具有不同的属性来报告组成员身份,或者可能无法通过属性跟踪组成员身份。根据您自己独特的 LDAP 配置来配置您的查询。如果未设置,
mongoldap
将无法授权用户使用 LDAP。