mongoldap

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 ，而不是在mongosh中。

本文档提供mongoldap的所有命令行选项的完整概述。

安装

mongoldap工具是MongoDB database Tools Extra包的一部分，可以与MongoDB Server一起安装，也可以独立安装。

使用

请考虑以下示例配置文件，该文件旨在支持通过 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 身份验证或授权时使用的用户名。

--password=<string>

--usermongoldap尝试 LDAP 身份验证时使用的 密码。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。

--ldapQueryPassword=<string | array>

仅在 MongoDB Enterprise 中可用。

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

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

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

ldapQueryPassword setParameter命令接受string或字符串数组。 如果将ldapQueryPassword设置为数组，则 MongoDB 按顺序尝试每个密码，直到成功为止。 使用密码数组滚动 LDAP 帐户密码，无需停机。

--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 支持以下值：

值	说明
simple	mongoldap 使用简单身份验证。
sasl	mongoldap 使用 SASL 协议进行身份验证。

如果指定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	LDAP 标识名 (DN) 格式模板，该模板将 match 正则表达式匹配的身份验证名称转换为 LDAP DN。每个大括号内的数值都替换为相应的正则表达式捕获组，这些捕获组是通过 match 正则表达式从身份验证用户名中提取而来的。 替换的结果必须是 RFC4514 转义字符串。	"cn={0},ou=engineering, dc=example,dc=com"
ldapQuery	LDAP 查询格式模板，该模板将匹配match正则表达式的身份验证名称插入到按照 RFC 4515和 RFC 4516编码的 LDAP 查询 URI 中。 每个大括号括起来的数值都会替换为相应的 正则表达式捕获组 通过match 表达式从身份验证用户名中提取。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将返回错误。

如果由于 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} 对应于string bob。 生成的输出是 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。

注意

对 RFC4515、 RFC4516 或 LDAP 查询的解释超出了 MongoDB 文档的范围。请直接查看 RFC 或使用您首选的 LDAP 资源。