mongoldap

摘要

MongoDB企业版提供mongoldap 用于测试MongoDB对运行中的LDAP服务器或服务器组的LDAP配置选项。

要验证配置文件中的LDAP选项，将 mongoldap 的 --config 选项设置为配置文件路径。

要测试LDAP配置选项，您必须指定一个 --user 和 --password。 mongoldap 模拟使用提供的配置选项和凭据对MongoDB服务器进行身份验证。

mongoldap 返回一个报告，其中包括LDAP身份验证或授权过程中的任何步骤的成功或失败情况。错误信息包括遇到的具体错误信息和解决错误的潜在建议。

在配置与 LDAP授权 相关的选项时，mongoldap 执行使用提供的配置选项和用户名构建的LDAP查询，并返回用户在 admin 数据库上具有权限的角色列表。

您可以在配置 LDAP授权角色 以进行用户访问控制时使用此信息。例如，使用 mongoldap 确保您的配置允许特权用户获得执行预期任务所需的角色。同样，使用 mongoldap 确保您的配置不允许非特权用户获得访问MongoDB服务器或执行未经授权操作的角色。

在配置与 LDAP身份验证 相关的选项时，使用 mongoldap 确保身份验证操作按预期工作。

从系统命令行运行 mongoldap，而不是在 mongosh.

本文档提供了关于 mongoldap 的所有命令行选项的全面概述。

安装

mongoldap 工具是 MongoDB 数据库工具额外包 的一部分，可以与 MongoDB 服务器一起 安装 或作为 独立安装。

用法

请考虑以下示例配置文件，该文件旨在通过Active Directory支持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>"以支持Active Directory。如果未找到，mongoldap将验证是否存在"_ldap._tcp.<DNS_NAME>"以支持SRV。如果找不到SRV记录，mongoldap会警告您使用"srv_raw:<DNS_NAME>"代替。

如果您的连接字符串指定了"srv_raw:<DNS_NAME>"，mongoldap将对"<DNS NAME>"执行SRV记录查找。

选项

--config=<filename>, -f=<filename>

指定运行时配置选项的配置文件。这些选项与命令行配置选项等效。有关更多信息，请参阅自管理配置文件选项。

mongoldap 使用与 自管理 LDAP 代理身份验证 或 自管理部署上的 LDAP 授权 相关的任何配置选项，用于测试 LDAP 身份验证或授权。

需要指定 --user。可能接受 --password 用于测试 LDAP 身份验证。

确保配置文件使用 ASCII 编码。mongoldap 实例不支持非 ASCII 编码的配置文件，包括 UTF-8。

--user=<string>

用于尝试 LDAP 身份验证或授权时 mongoldap 的用户名。

--password=<string>

用于 --user 的密码，以便 mongoldap 尝试 LDAP 身份验证。LDAP 授权不需要此密码。

--ldapServers=<host1>:<port>,<host2>:<port>,...,<hostN>:<port>

该LDAP服务器是用于mongoldap验证用户身份或确定用户在特定数据库上被授权执行的操作。如果指定的LDAP服务器有任何副本实例，您可以通过逗号分隔列表指定每个副本服务器的地址和端口。

如果您的LDAP基础设施将LDAP目录分割到多个LDAP服务器，请指定一个 LDAP服务器或其任何副本实例到--ldapServers。MongoDB支持RFC 4511 4.1.10中定义的LDAP引用。请勿使用--ldapServers列出您基础设施中的每个LDAP服务器。

如果未设置，则mongoldap无法使用LDAP身份验证或授权。

--ldapQueryUser=<字符串>

仅在MongoDB企业版中可用。

当连接到或查询LDAP服务器时，mongoldap 绑定的身份。

以下任何一项为真时，则必须指定

• 使用 LDAP授权。

• 使用username transformation.

• LDAP服务器禁止匿名绑定

必须与 --ldapQueryUser 一起使用 --ldapQueryPassword。

如果未设置，mongoldap 将不会尝试绑定到LDAP服务器。

注意

Windows MongoDB部署可以使用 --ldapBindWithOSDefaults 代替 --ldapQueryUser 和 --ldapQueryPassword。您不能同时指定 --ldapQueryUser 和 --ldapBindWithOSDefaults。

--ldapQueryPassword=<字符串 | 数组>

仅在MongoDB企业版中可用。

使用 --ldapQueryUser 绑定到LDAP服务器时使用的密码。您必须与 --ldapQueryUser 一起使用 --ldapQueryPassword。

如果未设置，mongoldap 将不会尝试绑定到LDAP服务器。

您可以在运行中的 mongoldap 上使用 setParameter 来配置此设置。

ldapQueryPasswordsetParameter 命令接受字符串或字符串数组。如果将 ldapQueryPassword 设置为数组，MongoDB 将按顺序尝试每个密码，直到成功。使用密码数组可以实现 LDAP 账户密码的平滑切换。

--ldapBindWithOSDefaults=<bool>

默认值: false

仅在 Windows 平台的 MongoDB 企业版中可用。

允许 mongoldap 在连接到 LDAP 服务器时使用您的 Windows 登录凭据进行身份验证或绑定。

仅在以下情况下需要

• 使用 LDAP授权。

• 使用username transformation.

• LDAP服务器禁止匿名绑定

使用 --ldapBindWithOSDefaults 来替换 --ldapQueryUser 和 --ldapQueryPassword。

--ldapBindMethod=<string>

默认值: simple

仅在MongoDB企业版中可用。

方法 mongoldap 用于对 LDAP 服务器进行认证。使用 --ldapQueryUser 和 --ldapQueryPassword 连接到 LDAP 服务器。

--ldapBindMethod 支持以下值

值	描述
simple	mongoldap 使用简单认证。
sasl	mongoldap 使用 SASL 协议进行认证。

如果您指定了 sasl，您可以使用 --ldapBindSaslMechanisms 配置可用的 SASL 机制。默认情况下，mongoldap 使用 DIGEST-MD5 机制。

--ldapBindSaslMechanisms=<string>

默认值: DIGEST-MD5

仅在MongoDB企业版中可用。

以逗号分隔的 SASL 机制列表，mongoldap 在对 LDAP 服务器进行认证时可以使用。必须至少有一种机制被 mongoldap 和 LDAP 服务器所接受。mongoldap 在运行时会动态加载主机上安装的任何 SASL 机制库。

在 mongoldap 主机和远程 LDAP 服务器主机上安装并配置所选 SASL 机制（们）的适当库。您的操作系统可能默认包含某些 SASL 库。请参考每个 SASL 机制的文档以获取有关安装和配置的指导。

如果您使用 GSSAPI SASL 机制与 自管理部署上的 Kerberos 认证 一起使用，请验证以下内容

Linux

• KRB5_CLIENT_KTNAME 环境变量解析为主机机的客户端 Linux Keytab 文件 的名称。有关 Kerberos 环境变量的更多信息，请参阅 Kerberos 文档。

• 客户端密钥表包含一个 用户主体，用于 mongoldap 连接到 LDAP 服务器并执行 LDAP 查询。

Windows

如果连接到 Active Directory 服务器，当用户登录系统时，Windows Kerberos 配置将自动生成一个 票据授予票据。将 --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企业版中可用。

默认情况下，mongoldap 创建一个与 LDAP 服务器加密的 TLS/SSL 连接。

对于 Linux 部署，您必须在 /etc/openldap/ldap.conf 文件中配置适当的 TLS 选项。操作系统包管理器在 MongoDB 企业版安装过程中通过 libldap 依赖项创建此文件。有关 TLS 选项的详细信息，请参阅 OpenLDAP ldap.conf 文档。

对于 Windows 部署，您必须将 LDAP 服务器 CA 证书添加到 Windows 证书管理工具中。该工具的名称和功能可能因操作系统版本而异。有关证书管理的更多信息，请参阅您版本的 Windows 文档。

将 --ldapTransportSecurity 设置为 none 以禁用 mongoldap 与 LDAP 服务器之间的 TLS/SSL。

警告

将 --ldapTransportSecurity 设置为 none 将在 mongoldap 和 LDAP 服务器之间传输纯文本信息，并可能传输凭据。

--ldapTimeoutMS=<int>

默认值: 10000

仅在MongoDB企业版中可用。

在毫秒中，mongoldap应等待LDAP服务器对请求做出响应的时间。

增加--ldapTimeoutMS的值，如果连接失败的原因是连接超时，则可能防止MongoDB服务器和LDAP服务器之间的连接失败。减少--ldapTimeoutMS的值，可以减少MongoDB等待LDAP服务器响应的时间。

--ldapUserToDNMapping=<string>

仅在MongoDB企业版中可用。

将提供给mongoldap进行身份验证的用户名映射到LDAP的区分名称（DN）。您可能需要使用--ldapUserToDNMapping来在以下情况下将用户名转换为LDAP DN

• 使用简单的LDAP绑定进行LDAP身份验证，其中用户使用不是完整LDAP DN的用户名对MongoDB进行身份验证。

• 使用需要DN的LDAP授权查询模板。

• 将使用不同身份验证机制（例如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"
替换	一个LDAP区分名称（DN）格式化模板，该模板将匹配正则表达式match的认证名称转换为LDAP DN。每个花括号内的数值被通过match正则表达式从认证用户名中提取出的相应的正则表达式捕获组替换。 替换的结果必须是一个RFC4514转义字符串。	"cn={0},ou=engineering, dc=example,dc=com"
ldapQuery	一个LDAP查询格式化模板，该模板将匹配正则表达式 match 得到的认证名称插入到遵守RFC4515和RFC4516的LDAP查询URI编码中。每个花括号包围的数字值将被通过 正则表达式捕获组 从认证用户名中提取出的相应正则表达式捕获组替换。 mongoldap 执行查询以针对LDAP服务器检索认证用户的LDAP DN。 mongoldap 需要恰好一个返回结果以使转换成功，否则 mongoldap 将跳过此转换。	"ou=engineering,dc=example, dc=com??one?(user={0})"

注意

关于RFC4514、RFC4515、RFC4516或LDAP查询的内容不包含在MongoDB文档中。请直接查阅RFC文档或使用您首选的LDAP资源。

对于数组中的每个文档，您必须使用substitution或ldapQuery之一。您不能在同一个文档中同时指定两者。

在进行身份验证或授权时，mongoldap 将按照给定顺序遍历数组中的每个文档，将身份验证用户名与 match 过滤器进行匹配。如果找到匹配项，mongoldap 将应用转换并使用输出结果进行用户身份验证。 mongoldap 不会检查数组中的剩余文档。

如果给定的文档与提供的身份验证名称不匹配，mongoldap 继续遍历文档列表以找到其他匹配项。如果在任何文档中都没有找到匹配项，或者文档描述的转换失败，mongoldap 将返回一个错误。

mongoldap 如果由于网络或对 LDAP 服务器的身份验证失败而无法评估其中一个转换，也会返回一个错误。 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} 对应于字符串 bob。生成的输出是 LDAP 查询 "ou=dba,dc=example,dc=com??one?(user=bob)"。 mongoldap 将此查询执行在 LDAP 服务器上，返回结果 "cn=bob,ou=dba,dc=example,dc=com"。

如果未设置 --ldapUserToDNMapping，则在尝试对 LDAP 服务器进行用户身份验证或授权时，mongoldap 不会对用户名应用任何转换。

--ldapAuthzQueryTemplate=<字符串>

仅在MongoDB企业版中可用。

一个相对的LDAP查询URL，格式符合 RFC4515 和 RFC4516，该URL由mongoldap执行以获取认证用户所属的LDAP组。查询相对于在--ldapServers中指定的主机或主机。

在URL中，您可以使用以下替换令牌

替换令牌	描述
{USER}	替换认证的用户名，或如果指定了 用户名映射，则替换转换后的用户名。
{PROVIDED_USER}	替换提供的用户名，即在认证或 LDAP转换之前。

在构造查询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授权用户。

注意

关于 RFC4515、RFC4516 或 LDAP 查询的内容超出了 MongoDB 文档的范围。请直接查看 RFC 或使用您偏好的 LDAP 资源。