mongoldap

Synopsis提要

MongoDB Enterprise provides mongoldap for testing MongoDB's LDAP configuration options against a running LDAP server or set of servers.MongoDB Enterprise提供了mongodap，用于针对正在运行的LDAP服务器或服务器集测试MongoDB的LDAP配置选项。

To validate the LDAP options in the configuration file, set the mongoldap --config option to the configuration file's path.要验证配置文件中的LDAP选项，请将mongoldap --config选项设置为配置文件的路径。

To test the LDAP configuration options, you must specify a --user and --password. 要测试LDAP配置选项，必须指定--user和--password。mongoldap simulates authentication to a MongoDB server running with the provided configuration options and credentials.模拟对使用所提供的配置选项和凭据运行的MongoDB服务器的身份验证。

mongoldap returns a report that includes the success or failure of any step in the LDAP authentication or authorization procedure. 返回一个报告，其中包括LDAP身份验证或授权过程中任何步骤的成功或失败。Error messages include information on specific errors encountered and potential advice for resolving the error.错误消息包括有关遇到的特定错误的信息以及解决错误的潜在建议。

When configuring options related to LDAP authorization, mongoldap executes an LDAP query constructed using the provided configuration options and username, and returns a list of roles on the admin database which the user is authorized for.在配置与LDAP授权相关的选项时，mongoldap执行使用所提供的配置选项和用户名构建的LDAP查询，并返回管理员数据库中用户授权的角色列表。

You can use this information when configuring LDAP authorization roles for user access control. 在为用户访问控制配置LDAP授权角色时，可以使用此信息。For example, use mongoldap to ensure your configuration allows privileged users to gain the necessary roles to perform their expected tasks. 例如，使用mongoldap确保您的配置允许权限用户获得执行其预期任务所需的角色。Similarly, use mongoldap to ensure your configuration disallows non-privileged users from gaining roles for accessing the MongoDB server, or performing unauthorized actions.同样，使用mongoldap确保您的配置不允许非权限用户获得访问MongoDB服务器的角色，或执行未经授权的操作。

When configuring options related to LDAP authentication, use mongoldap to ensure that the authentication operation works as expected.配置与LDAP身份验证相关的选项时，请使用mongoldap确保身份验证操作按预期工作。

Run mongoldap from the system command line, not in the mongosh.从系统命令行运行mongodap，而不是在mongosh中。

This document provides a complete overview of all command line options for mongoldap.本文档提供了mongoldap的所有命令行选项的完整概述。

Installation安装

The mongoldap tool is part of the MongoDB Database Tools Extra package, and can be installed with the MongoDB Server or as a standalone installation.mongoldap工具是MongoDB Database Tools Extra包的一部分，可以与MongoDB Server一起安装，也可以作为独立安装。

Usage

Consider the following sample configuration file, designed to support LDAP authentication and authorization via 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"

You can use mongoldap to validate the configuration file, which returns a report of the procedure. You must specify a username and password for mongoldap.

mongoldap --config=<path-to-config> --user="bob@dba.example.com" --password="secret123"

If the provided credentials are valid, and the LDAP options in the configuration files are valid, the output might be as follows:如果提供的凭据有效，并且配置文件中的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:
...

Behavior行为

Starting in MonogoDB 5.1, mongoldap supports prefixing LDAP server with srv: and srv_raw:.从MonogoDB 5.1开始，mongodap支持在LDAP服务器前添加srv:和srv_raw:。

If your connection string specifies "srv:<DNS_NAME>", mongoldap verifies that "_ldap._tcp.gc._msdcs.<DNS_NAME>" exists for SRV to support Active Directory. 如果连接字符串指定了"srv:<DNS_NAME>"，则mongoldap会为SRV验证"_ldap._tcp.gc._msdcs.<DNS_NAME>"的存在，以支持活动目录。If not found, it verifies "_ldap._tcp.<DNS_NAME>" exists for SRV. 如果不存在，它会为SRV验证"_ldap._tcp.<DNS_NAME>"的存在。If an SRV record cannot be found, mongoldap warns you to use "srv_raw:<DNS_NAME>" instead. 如果找不到SRV记录，mongoldap会警告你改用"srv_raw:<DNS_NAME>"。mongoldap does the reverse check for "srv_raw:<DNS_NAME>" by checking for "_ldap._tcp.<DNS NAME>".通过检查"_ldap._tcp.<DNS NAME>"来对"srv_raw:<DNS_NAME>"执行反向检查。

Options选项

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

Specifies a configuration file for runtime configuration options. The options are equivalent to the command-line configuration options. See Configuration File Options for more information.

mongoldap uses any configuration options related to LDAP Proxy Authentication or LDAP Authorization for testing LDAP authentication or authorization.

Requires specifying --user. May accept --password for testing LDAP authentication.

Ensure the configuration file uses ASCII encoding. The mongoldap instance does not support configuration files with non-ASCII encoding, including UTF-8.

--user=<string>

Username for mongoldap to use when attempting LDAP authentication or authorization.

--password=<string>

Password of the --user for mongoldap to use when attempting LDAP authentication. Not required for LDAP authorization.

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

The LDAP server against which the mongoldap authenticates users or determines what actions a user is authorized to perform on a given database. If the LDAP server specified has any replicated instances, you may specify the host and port of each replicated server in a comma-delimited list.

If your LDAP infrastructure partitions the LDAP directory over multiple LDAP servers, specify one LDAP server or any of its replicated instances to --ldapServers. MongoDB supports following LDAP referrals as defined in RFC 4511 4.1.10. Do not use --ldapServers for listing every LDAP server in your infrastructure.

If unset, mongoldap cannot use LDAP authentication or authorization.

--ldapQueryUser=<string>

Available in MongoDB Enterprise only.

The identity with which mongoldap binds as, when connecting to or performing queries on an LDAP server.当连接到LDAP服务器或在LDAP服务器上执行查询时，mongodap绑定为的标识。

Only required if any of the following are true:仅当以下任何一项为真时才需要：

• Using LDAP authorization.使用LDAP授权。
• Using an LDAP query for username transformation.使用LDAP查询进行用户名转换。
• The LDAP server disallows anonymous bindsLDAP服务器不允许匿名绑定

You must use --ldapQueryUser with --ldapQueryPassword.必须将--ldapQueryUser与--ldapQueryPassword一起使用。

If unset, mongoldap will not attempt to bind to the LDAP server.如果未设置，mongodap将不会尝试绑定到LDAP服务器。

Note

Windows MongoDB deployments can use --ldapBindWithOSDefaults instead of --ldapQueryUser and --ldapQueryPassword. You cannot specify both --ldapQueryUser and --ldapBindWithOSDefaults at the same time.

Available in MongoDB Enterprise only.

The password used to bind to an LDAP server when using --ldapQueryUser. You must use --ldapQueryPassword with --ldapQueryUser.

If not set, mongoldap does not attempt to bind to the LDAP server.

You can configure this setting on a running mongoldap using setParameter.

Starting in MongoDB 4.4, the ldapQueryPassword setParameter command accepts either a string or an array of strings. If ldapQueryPassword is set to an array, MongoDB tries each password in order until one succeeds. Use a password array to roll over the LDAP account password without downtime.使用密码数组可以在不停机的情况下滚动LDAP帐户密码。

--ldapBindWithOSDefaults=<bool>

Default: false

Available in MongoDB Enterprise for the Windows platform only.仅适用于Windows平台的MongoDB Enterprise。

Allows mongoldap to authenticate, or bind, using your Windows login credentials when connecting to the LDAP server.允许mongoldap在连接到LDAP服务器时使用您的Windows登录凭据进行身份验证或绑定。

Only required if:只有在以下情况下才需要：

• Using LDAP authorization.使用LDAP授权。
• Using an LDAP query for username transformation.使用LDAP查询进行用户名转换。
• The LDAP server disallows anonymous bindsLDAP服务器不允许匿名绑定

Use --ldapBindWithOSDefaults to replace --ldapQueryUser and --ldapQueryPassword.使用--ldapBindWithOSDefaults替换--ldapQueryUser和--ldapQueryPassword。

--ldapBindMethod=<string>

Default: simple

Available in MongoDB Enterprise only.

The method mongoldap uses to authenticate to an LDAP server. Use with --ldapQueryUser and --ldapQueryPassword to connect to the LDAP server.

--ldapBindMethod supports the following values:

Value值	Description描述
simple	mongoldap uses simple authentication.
sasl	mongoldap uses SASL protocol for authentication.

If you specify sasl, you can configure the available SASL mechanisms using --ldapBindSaslMechanisms. mongoldap defaults to using DIGEST-MD5 mechanism.

--ldapBindSaslMechanisms=<string>

Default: DIGEST-MD5

Available in MongoDB Enterprise only.

A comma-separated list of SASL mechanisms mongoldap can use when authenticating to the LDAP server. The mongoldap and the LDAP server must agree on at least one mechanism. The mongoldap dynamically loads any SASL mechanism libraries installed on the host machine at runtime.

Install and configure the appropriate libraries for the selected SASL mechanism(s) on both the mongoldap host and the remote LDAP server host. Your operating system may include certain SASL libraries by default. Defer to the documentation associated with each SASL mechanism for guidance on installation and configuration.

If using the GSSAPI SASL mechanism for use with Kerberos Authentication, verify the following for the mongoldap host machine:

Linux

• The KRB5_CLIENT_KTNAME environment variable resolves to the name of the client Linux Keytab Files for the host machine. For more on Kerberos environment variables, please defer to the Kerberos documentation.
• The client keytab includes a User Principal for the mongoldap to use when connecting to the LDAP server and execute LDAP queries.

Windows

If connecting to an Active Directory server, the Windows Kerberos configuration automatically generates a Ticket-Granting-Ticket when the user logs onto the system. Set --ldapBindWithOSDefaults to true to allow mongoldap to use the generated credentials when connecting to the Active Directory server and execute queries.

Set --ldapBindMethod to sasl to use this option.

Note

For a complete list of SASL mechanisms see the IANA listing. Defer to the documentation for your LDAP or Active Directory service for identifying the SASL mechanisms compatible with the service.

MongoDB is not a source of SASL mechanism libraries, nor is the MongoDB documentation a definitive source for installing or configuring any given SASL mechanism. For documentation and support, defer to the SASL mechanism library vendor or owner.

For more information on SASL, defer to the following resources:

• For Linux, please see the Cyrus SASL documentation.
• For Windows, please see the Windows SASL documentation.

--ldapTransportSecurity=<string>

Default: tls

Available in MongoDB Enterprise only.

By default, mongoldap creates a TLS/SSL secured connection to the LDAP server.

For Linux deployments, you must configure the appropriate TLS Options in /etc/openldap/ldap.conf file. Your operating system's package manager creates this file as part of the MongoDB Enterprise installation, via the libldap dependency. See the documentation for TLS Options in the ldap.conf OpenLDAP documentation for more complete instructions.

For Windows deployment, you must add the LDAP server CA certificates to the Windows certificate management tool. The exact name and functionality of the tool may vary depending on operating system version. Please see the documentation for your version of Windows for more information on certificate management.

Set --ldapTransportSecurity to none to disable TLS/SSL between mongoldap and the LDAP server.

Warning

Setting --ldapTransportSecurity to none transmits plaintext information and possibly credentials between mongoldap and the LDAP server.

--ldapTimeoutMS=<int>

Default: 10000

Available in MongoDB Enterprise only.

The amount of time in milliseconds mongoldap should wait for an LDAP server to respond to a request.

Increasing the value of --ldapTimeoutMS may prevent connection failure between the MongoDB server and the LDAP server, if the source of the failure is a connection timeout. Decreasing the value of --ldapTimeoutMS reduces the time MongoDB waits for a response from the LDAP server.

--ldapUserToDNMapping=<string>

Available in MongoDB Enterprise only.

Maps the username provided to mongoldap for authentication to a LDAP Distinguished Name (DN). You may need to use --ldapUserToDNMapping to transform a username into an LDAP DN in the following scenarios:

• Performing LDAP authentication with simple LDAP binding, where users authenticate to MongoDB with usernames that are not full LDAP DNs.
• Using an LDAP authorization query template that requires a DN.
• Transforming the usernames of clients authenticating to Mongo DB using different authentication mechanisms (e.g. x.509, kerberos) to a full LDAP DN for authorization.

--ldapUserToDNMapping expects a quote-enclosed JSON-string representing an ordered array of documents. Each document contains a regular expression match and either a substitution or ldapQuery template used for transforming the incoming username.

Each document in the array has the following form:

{
  match: "<regex>"
  substitution: "<LDAP DN>" | ldapQuery: "<LDAP Query>"
}

Field字段	Description描述	Example示例
match	An ECMAScript-formatted regular expression (regex) to match against a provided username. Each parenthesis-enclosed section represents a regex capture group used by substitution or ldapQuery.	"(.+)ENGINEERING" "(.+)DBA"
substitution	An LDAP distinguished name (DN) formatting template that converts the authentication name matched by the match regex into a LDAP DN. Each curly bracket-enclosed numeric value is replaced by the corresponding regex capture group extracted from the authentication username via the match regex. The result of the substitution must be an RFC4514 escaped string.	"cn={0},ou=engineering, dc=example,dc=com"
ldapQuery	A LDAP query formatting template that inserts the authentication name matched by the match regex into an LDAP query URI encoded respecting RFC4515 and RFC4516. Each curly bracket-enclosed numeric value is replaced by the corresponding regex capture group extracted from the authentication username via the match expression. mongoldap executes the query against the LDAP server to retrieve the LDAP DN for the authenticated user. mongoldap requires exactly one returned result for the transformation to be successful, or mongoldap skips this transformation.	"ou=engineering,dc=example, dc=com??one?(user={0})"

Note

An explanation of RFC4514, RFC4515, RFC4516, or LDAP queries is out of scope for the MongoDB Documentation. Please review the RFC directly or use your preferred LDAP resource.

For each document in the array, you must use either substitution or ldapQuery. You cannot specify both in the same document.

When performing authentication or authorization, mongoldap steps through each document in the array in the given order, checking the authentication username against the match filter. If a match is found, mongoldap applies the transformation and uses the output for authenticating the user. mongoldap does not check the remaining documents in the array.

If the given document does not match the provided authentication name, mongoldap continues through the list of documents to find additional matches. If no matches are found in any document, or the transformation the document describes fails, mongoldap returns an error.

Starting in MongoDB 4.4, mongoldap also returns an error if one of the transformations cannot be evaluated due to networking or authentication failures to the LDAP server. mongoldap rejects the connection request and does not check the remaining documents in the array.

Starting in MongoDB 5.0, --ldapUserToDNMapping accepts an empty string "" or empty array [ ] in place of a mapping documnent. If providing an empty string or empty array to --ldapUserToDNMapping, MongoDB will map the authenticated username as the LDAP DN. Previously, providing an empty mapping document would cause mapping to fail.

Example

The following shows two transformation documents. The first document matches against any string ending in @ENGINEERING, placing anything preceeding the suffix into a regex capture group. The second document matches against any string ending in @DBA, placing anything preceeding the suffix into a regex capture group.

Important

You must pass the array to --ldapUserToDNMapping as a string.

"[
   {
      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})"

   }

]"

A user with username alice@ENGINEERING.EXAMPLE.COM matches the first document. The regex capture group {0} corresponds to the string alice. The resulting output is the DN "cn=alice,ou=engineering,dc=example,dc=com".

A user with username bob@DBA.EXAMPLE.COM matches the second document. The regex capture group {0} corresponds to the string bob. The resulting output is the LDAP query "ou=dba,dc=example,dc=com??one?(user=bob)". mongoldap executes this query against the LDAP server, returning the result "cn=bob,ou=dba,dc=example,dc=com".

If --ldapUserToDNMapping is unset, mongoldap applies no transformations to the username when attempting to authenticate or authorize a user against the LDAP server.

--ldapAuthzQueryTemplate=<string>

Available in MongoDB Enterprise only.

A relative LDAP query URL formatted conforming to RFC4515 and RFC4516 that mongoldap executes to obtain the LDAP groups to which the authenticated user belongs to. The query is relative to the host or hosts specified in --ldapServers.

In the URL, you can use the following substituion tokens:

Substitution Token	Description描述
{USER}	Substitutes the authenticated username, or the transformed username if a username mapping is specified.
{PROVIDED_USER}	Substitutes the supplied username, i.e. before either authentication or LDAP transformation. New in version 4.2. 4.2版新增。

When constructing the query URL, ensure that the order of LDAP parameters respects RFC4516:

[ dn  [ ? [attributes] [ ? [scope] [ ? [filter] [ ? [Extensions] ] ] ] ] ]

If your query includes an attribute, mongoldap assumes that the query retrieves a the DNs which this entity is member of.

If your query does not include an attribute, mongoldap assumes the query retrieves all entities which the user is member of.

For each LDAP DN returned by the query, mongoldap assigns the authorized user a corresponding role on the admin database. If a role on the on the admin database exactly matches the DN, mongoldap grants the user the roles and privileges assigned to that role. See the db.createRole() method for more information on creating roles.

Example

This LDAP query returns any groups listed in the LDAP user object's memberOf attribute.

"{USER}?memberOf?base"

Your LDAP configuration may not include the memberOf attribute as part of the user schema, may possess a different attribute for reporting group membership, or may not track group membership through attributes. Configure your query with respect to your own unique LDAP configuration.

If unset, mongoldap cannot authorize users using LDAP.

Note

An explanation of RFC4515, RFC4516 or LDAP queries is out of scope for the MongoDB Documentation. Please review the RFC directly or use your preferred LDAP resource.