LDAP AuthorizationLDAP授权

On this page本页内容

MongoDB Enterprise supports querying an LDAP server for the LDAP groups to which the authenticated user belongs. 支持在LDAP服务器上查询经过身份验证的用户所属的LDAP组。MongoDB maps the distinguished names (DN) of each returned group to roles on the admin database. MongoDB将每个返回组的可分辨名称（DN）映射到admin数据库上的角色。MongoDB authorizes the user based on the mapped roles and their associated privileges. MongoDB根据映射的角色及其相关权限对用户进行授权。See LDAP Authorization for more information.有关更多信息，请参阅LDAP授权。

The LDAP Authorization process is summarized below:LDAP授权过程总结如下：

  1. A client connects to MongoDB and performs authentication with any authentication mechanism that supports external authentication.客户端连接到MongoDB，并使用支持外部身份验证的任何身份验证机制执行身份验证。

    To use Client Sessions and Causal Consistency Guarantees with $external authentication users (Kerberos, LDAP, or x.509 users), usernames cannot be greater than 10k bytes.要对$external身份验证用户（Kerberos、LDAP或x.509用户）使用客户端会话和因果一致性保证，用户名不能超过10k字节。

  2. MongoDB binds to the LDAP server specified with security.ldap.servers using the credentials specified with security.ldap.bind.queryUser and security.ldap.bind.queryPassword.MongoDB使用security.ldap.bind.queryUser和security.ldap.bind.queryPassword指定的凭据绑定到security.ldap.servers指定的LDAP服务器。

    MongoDB uses simple binding by default, but can use sasl binding instead if configured in security.ldap.bind.method and security.ldap.bind.saslMechanisms.默认情况下，MongoDB使用简单绑定，但如果在security.ldap.bind.method和security.ldap.bind.saslMechanisms中配置，则可以使用sasl绑定。

  3. MongoDB constructs an LDAP query using the security.ldap.authz.queryTemplate and queries the LDAP server for the authenticated user's group membership.MongoDB使用security.ldap.authz.queryTemplate构造LDAP查询，并向LDAP服务器查询经过身份验证的用户的组成员身份。

    MongoDB can use the security.ldap.userToDNMapping option to transform the username for supporting the query template.MongoDB可以使用security.ldap.userToDNMapping选项转换用户名以支持查询模板。

  4. The LDAP server evaluates the query and returns the list of groups to which the authenticated user belongs.LDAP服务器评估查询并返回经过身份验证的用户所属的组的列表。
  5. MongoDB authorizes the user to perform actions on the server by mapping each returned group's Distinguished Name (DN) into a role on the admin database. MongoDB通过将每个返回组的可分辨名称（DN）映射到admin数据库上的角色，授权用户在服务器上执行操作。If a returned group DN exactly matches the name of an existing role on the admin database, MongoDB grants the user the roles and privileges assigned to that role. 如果返回的组DN与admin数据库中现有角色的名称完全匹配，MongoDB将向用户授予分配给该角色的角色和权限。See MongoDB Roles for LDAP Authorization for more information.有关更多信息，请参阅LDAP授权的MongoDB角色。
  6. The client can perform actions on the MongoDB server which require the roles or privileges granted to the authenticated user.客户端可以在MongoDB服务器上执行操作，这些操作需要授予经过身份验证的用户角色或权限。
  7. At an interval defined by ldapUserCacheInvalidationInterval, MongoDB flushes the $external cache. 按照ldapUserCacheInvalidationInterval定义的间隔，MongoDB刷新$external缓存。Prior to executing subsequent operations performed by externally authorized users, MongoDB re-acquires their group membership from the LDAP server.在执行由外部授权用户执行的后续操作之前，MongoDB从LDAP服务器重新获取其组成员资格。

Considerations考虑因素

A full description of LDAP is beyond the scope of this documentation. LDAP的完整描述超出了本文档的范围。This page assumes prior knowledge of LDAP.本页假定您已了解LDAP。

This documentation only describes MongoDB LDAP authorization, and does not replace other resources on LDAP. 本文档仅描述MongoDB LDAP授权，不替换LDAP上的其他资源。We encourage you to thoroughly familiarize yourself with LDAP and its related subject matter before configuring LDAP authentication.我们鼓励您在配置LDAP身份验证之前彻底熟悉LDAP及其相关主题。

MongoDB can provide professional services for optimal configuration of LDAP authorization for your MongoDB deployment.MongoDB可以为您的MongoDB部署提供优化LDAP授权配置的专业服务。

Compatible Authentication Mechanism兼容认证机制

The following authentication mechanisms are compatible with MongoDB LDAP authorization:以下身份验证机制与MongoDB LDAP授权兼容：

Connection Pool连接池

Starting in version 4.2.0, when connecting to the LDAP server for authentication/authorization, MongoDB, by default:从4.2.0版开始，连接LDAP服务器进行身份验证/授权时，默认情况下为MongoDB：

  • Uses connection pooling if run:在以下情况下使用连接池：

    • on Windows or
    • on Linux where MongoDB Enterprise binaries are linked against libldap_r.在Linux上，MongoDB企业二进制文件链接到libldap_r。

  • Does not use connection pooling if run:在以下情况下不使用连接池：

    • on Linux where MongoDB Enterprise binaries are linked against libldap.在Linux上，MongoDB企业二进制文件与libldap链接。

To change the connection pooling behavior, update the ldapUseConnectionPool parameter.要更改连接池行为，请更新ldapUseConnectionPool参数。

libldap and libldap_r

For MongoDB 4.2 (and 4.0.9) Enterprise binaries linked against libldap (such as when running on RHEL), access to the libldap is synchronized, incurring some performance/latency costs.对于与libldap链接的MongoDB 4.2（和4.0.9）企业二进制文件（例如在RHEL上运行时），对libldap的访问是同步的，会产生一些性能/延迟成本。

For MongoDB 4.2 (and 4.0.9) Enterprise binaries linked against libldap_r, there is no change in behavior from earlier MongoDB versions.对于与libldap_r链接的MongoDB 4.2（和4.0.9）企业二进制文件，其行为与早期的MongoDB版本没有变化。

User Management用户管理

With LDAP authorization, user creation and management occurs on the LDAP server. 通过LDAP授权，用户创建和管理在LDAP服务器上进行。MongoDB requires creation of roles on the admin database, with the name of each role exactly matching a LDAP group Distinguished Name (DN). MongoDB要求在admin数据库上创建角色，每个角色的名称与LDAP组可分辨名称（DN）完全匹配。This is in contrast to MongoDB managed authorization, which requires creating users on the $external database.这与MongoDB托管授权不同，后者需要在$external数据库上创建用户。

To manage roles on the MongoDB server, authenticate as a user whose group membership corresponds to a admin database role with role administration privileges, such as those provided by userAdmin. 要管理MongoDB服务器上的角色，请以用户身份进行身份验证，该用户的组成员资格对应于具有角色管理权限（如userAdmin提供的权限）的admin数据库角色。Create or update roles corresponding to LDAP group DNs such that users with membership in that group receive the appropriate roles and privileges.创建或更新与LDAP组DNs对应的角色，以使该组中的成员资格用户获得适当的角色和权限。

For example, an LDAP group for database administrators might have a role with administrative roles and privileges. 例如，数据库管理员的LDAP组可能具有具有管理角色和权限的角色。An LDAP group for marketing or analytics users may have a role with only have read privileges on certain databases.市场营销或分析用户的LDAP组可能具有仅对某些数据库具有读取权限的角色。

Important重要

When configuring a role for a corresponding LDAP Group, remember that all users with membership in that group can receive the configured roles and privileges. 为相应的LDAP组配置角色时，请记住，在该组中具有成员资格的所有用户可以接收配置的角色和权限。Consider applying the principle of least privilege when configuring MongoDB roles, LDAP groups, or group membership.在配置MongoDB角色、LDAP组或组成员身份时，请考虑应用最小权限原则。

If no role with role administration privileges exists AND no non-$external user with these privileges exists, you effectively cannot perform user management, as no new or existing roles can be altered to reflect additions or changes to groups or group membership on the LDAP server.如果不存在具有角色管理权限的角色，并且不存在具有这些权限的非$external用户，则实际上无法执行用户管理，因为不能更改任何新的或现有的角色，以反映对LDAP服务器上的组或组成员身份的添加或更改。

To remedy a scenario where you cannot manage roles on the MongoDB server, perform the following procedure:要纠正无法管理MongoDB服务器上角色的情况，请执行以下过程：

  1. Restart the MongoDB server without authentication and LDAP authorization在没有身份验证和LDAP授权的情况下重新启动MongoDB服务器
  2. Create a role on the admin database whose name corresponds to the appropriate LDAP group Distinguished Name. 在admin数据库上创建一个角色，其名称对应于相应的LDAP组可分辨名称。When choosing a group DN, consider which group is most appropriate for database administration.选择组DN时，请考虑哪个组最适合数据库管理。
  3. Restart the MongoDB server with authentication and LDAP authorization使用身份验证和LDAP授权重新启动MongoDB服务器
  4. Authenticate as a user with membership in the group corresponding to the created administrative role.以用户身份进行身份验证，该用户在与所创建的管理角色对应的组中具有成员身份。

Existing Users现有用户

A MongoDB server using LDAP for authorization makes any existing users on the $external database inaccessible. 使用LDAP进行授权的MongoDB服务器使$external数据库上的任何现有用户都无法访问。If there are existing users in $external database, you must meet the following requirements for each user on the $external database to ensure continued access:如果$external database中有现有用户，则必须满足$external database中每个用户的以下要求，以确保继续访问：

  • User has a corresponding user object on the LDAP server用户在LDAP服务器上有相应的用户对象
  • User object has membership in the appropriate LDAP groups用户对象在相应的LDAP组中具有成员身份
  • MongoDB has roles on the admin database named for the user's LDAP groups, such that the granted roles and privileges are identical to those granted to the non-$external user.MongoDB在以用户的LDAP组命名的admin数据库上有角色，因此授予的角色和权限与授予非$external用户的角色和权限相同。

If you want to continue allowing access by users not on the $external database, ensure the authenticationMechanisms parameter includes SCRAM-SHA-1 and/or SCRAM-SHA-256 as appropriate. 如果要继续允许不在$external数据库上的用户访问，请确保authenticationMechanisms参数包括SCRAM-SHA-1和/或SCRAM-HA-256（视情况而定）。Alternatively, apply the requirements listed above for transitioning those users to LDAP authorization.或者，应用上面列出的要求将这些用户转换为LDAP授权。

Replica Sets复制集

For replica sets, configure LDAP authorization on the secondary and arbiter members first before configuring the primary. 对于副本集，在配置主成员之前，首先在辅助成员和仲裁器成员上配置LDAP授权。This also applies to shard replica sets, or config server replica sets. 这也适用于分片副本集或配置服务器副本集。Configure one replica set member at a time to maintain a majority of members for write availability.一次配置一个副本集成员，以保持大多数成员的写可用性。

Sharded Clusters分片群集

In sharded clusters, you must configure LDAP authorization on the config servers for cluster-level users. 在分片集群中，必须在配置服务器上为集群级用户配置LDAP授权。You can optionally configure LDAP authorization on each shard for shard-local users.您可以选择在每个分片上为分片本地用户配置LDAP授权。

Configuration配置

You must configure the following settings to use LDAP Authorization:必须配置以下设置才能使用LDAP授权：

To use LDAP for authorization via operating system libraries, specify the following settings as a part of your mongod or mongos configuration file:要通过操作系统库使用LDAP进行授权，请在mongod或mongos配置文件中指定以下设置：

Option选项Description描述Required
security.ldap.serversQuote-enclosed comma-separated list of LDAP servers in host[:port] format.以host[:port]格式附上逗号分隔的LDAP服务器列表。 YES
security.ldap.authz.queryTemplate

An RFC4515 and RFC4516 LDAP formatted query URL template executed by MongoDB to obtain the LDAP groups to which the user belongs to. MongoDB执行RFC4515和RFC4516LDAP格式的查询URL模板，以获取用户所属的LDAP组。The query is relative to the host or hosts specified in servers.查询是相对于servers中指定的一个或多个主机的。

You can use the following tokens in the template:您可以在模板中使用以下令牌：

  • {USER}
    Substitutes the authenticated username, or the transformed username, into the LDAP query.将经过身份验证的用户名或转换后的用户名替换为LDAP查询。
  • {PROVIDED_USER}
    Substitutes the supplied username, i.e. before either authentication or LDAP transformation, into the LDAP query. (Available starting in version 4.2)在验证或LDAP转换之前，将提供的用户名替换为LDAP查询。（从4.2版开始提供）

Only mongod supports this parameter. 只有mongod支持此参数。mongos defers to this setting as configured on its config serversmongos遵从其配置服务器上配置的此设置

YES
security.ldap.bind.queryUser

The identity the MongoDB server binds as when connecting to and executing operations and queries on an LDAP server.连接到LDAP服务器并在其上执行操作和查询时，MongoDB服务器绑定的身份。

Use with queryPassword.与queryPassword一起使用。

The user specified must have the appropriate privileges to support the LDAP queries generated from the configured queryTemplate.指定的用户必须具有适当的权限，以支持从配置的queryTemplate生成的LDAP查询。

YES
security.ldap.bind.queryPasswordThe password used to bind to an LDAP server when using queryUser.使用queryUser时用于绑定到LDAP服务器的密码。 YES
security.ldap.bind.method

Used to specify the method the mongod or mongos uses to authenticate, or bind, to the LDAP server. 用于指定mongod或mongos用于验证或绑定LDAP服务器的方法。Specify sasl to use one of the SASL protocols defined in security.ldap.bind.saslMechanisms.指定sasl以使用security.ldap.bind.saslMechanisms中定义的SASL协议之一。

Defaults to simple.

NO, unless using sasl for binding to the LDAP server.不，除非使用sasl绑定到LDAP服务器。
security.ldap.bind.saslMechanisms

Used to specify the SASL mechanisms mongod or mongos can use when authenticating or binding to the LDAP server. 用于指定mongod或mongos在验证或绑定到LDAP服务器时可以使用的SASL机制。MongoDB and the LDAP server must agree on at least one SASL mechanism.MongoDB和LDAP服务器必须至少就一种SASL机制达成一致。

Defaults to DIGEST-MD5.默认为DIGEST-MD5。

NO, unless setting method to sasl, and you need different or additional SASL mechanisms.不，除非将method设置为sasl，并且您需要不同的或附加的sasl机制。
security.ldap.bind.useOSDefaultsWindows MongoDB deployments can use the operating system credentials in place of queryUser and queryPassword for authenticating or binding as when connecting to the LDAP server.Windows MongoDB部署可以使用操作系统凭据代替queryUser和queryPassword进行身份验证或绑定，就像连接到LDAP服务器一样。 NO, unless replacing queryUser and queryPassword.不，除非替换queryUser和queryPassword。
security.ldap.userToDNMappingDepending on your queryTemplate, the authenticated client username may require transformation to support the LDAP query URL. 根据您的queryTemplate，经过身份验证的客户端用户名可能需要转换以支持LDAP查询URL。userToDNMapping allows MongoDB to transform incoming usernames.允许MongoDB转换传入的用户名。 NO, unless client usernames require transformation into LDAP DNs.不，除非客户端用户名需要转换为LDAP DNs。

LDAP Query TemplateLDAP查询模板

MongoDB uses the security.ldap.authz.queryTemplate to create an RFC4516 formatted LDAP query URL. MongoDB使用security.ldap.authz.queryTemplate创建RFC4516格式的LDAP查询URL。In the template, you can use either:

  • {USER} placeholder to substitute the authenticated username into the LDAP query URL. 将经过身份验证的用户名替换为LDAP查询URL的占位符。If MongoDB transformed the username using userToDNMapping, MongoDB replaces the {USER} token with the transformed username when constructing the LDAP query URL.如果MongoDB使用userToDNMapping转换用户名，则在构造LDAP查询URL时，MongoDB会用转换后的用户名替换{USER}标记。
  • {PROVIDED_USER} placeholder to substitute the supplied username, i.e. before either authentication or LDAP transformation, into the LDAP query.在验证或LDAP转换之前，将提供的用户名替换为LDAP查询的占位符。

Design the query template to retrieve the user's groups.设计查询模板以检索用户的组。

Example

The following query template returns any groups listed in the LDAP user object's memberOf attribute. 以下查询模板返回LDAP用户对象的memberOf属性中列出的任何组。This query assumes the memberOf attribute exists - your specific LDAP deployment may use a different attribute or methodology for tracking group membership. 此查询假设memberOf属性存在——您的特定LDAP部署可能会使用不同的属性或方法来跟踪组成员身份。This query also assumes the user authenticates using their full LDAP DN as their username.此查询还假设用户使用完整的LDAP DN作为用户名进行身份验证。

"{USER}?memberOf?base"

The LDAP query URL must conform to the format defined in RFC4516:LDAP查询URL必须符合RFC4516中定义的格式：

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

Consider the definition of each component, as quoted from RFC4516:考虑RFC4516中引用的每个组件的定义：

The dn is an LDAP Distinguished Name using the string format described in RFC4514. dn是使用RFC4514中描述的字符串格式的LDAP可分辨名称。It identifies the base object of the LDAP search or the target of a non-search operation.它标识LDAP搜索的基本对象或非搜索操作的目标。

The attributes construct is used to indicate which attributes should be returned from the entry or entries.attributes构造用于指示应该从一个或多个条目返回哪些属性。

The scope construct is used to specify the scope of the search to perform in the given LDAP server. scope构造用于指定要在给定LDAP服务器中执行的搜索范围。The allowable scopes are "base" for a base object search, "one" for a one-level search, or "sub" for a subtree search.允许的范围是基本对象搜索的“基本”，一级搜索的“一”，或子树搜索的“子”。

The filter is used to specify the search filter to apply to entries within the specified scope during the search. filter用于指定搜索期间应用于指定范围内的条目的搜索筛选器。It has the format specified in [RFC4515].它具有[RFC4515]中指定的格式。

The extensions construct provides the LDAP URL with an extensibility mechanism, allowing the capabilities of the URL to be extended in the future.extensions构造为LDAP URL提供了可扩展性机制，允许将来扩展URL的功能。

If the query includes an attribute, MongoDB assumes the query retrieves a the DNs which this entity is member of.如果查询包含一个attribute，MongoDB将假定查询检索该实体所属的DNs。

If the query does not include an attribute, MongoDB assumes the query retrieves all entities for which the user is member of.如果查询不包含属性，MongoDB将假定查询检索用户所属的所有实体。

MongoDB currently ignores any extensions specified in the LDAP query.MongoDB目前会忽略LDAP查询中指定的任何扩展。

Important重要

A full description of RFC4516 or LDAP query URL construction is out of scope for this documentation.RFC4516或LDAP查询URL构造的完整描述不在本文档范围内。

Tutorials教程

The following tutorials contain procedures for connecting to an LDAP server via the Operating System LDAP libraries:以下教程包含通过操作系统LDAP库连接到LDAP服务器的过程：

Connecting to a MongoDB server using LDAP Authorization使用LDAP授权连接到MongoDB服务器

When using LDAP for authorization, users connecting via mongosh must:使用LDAP进行授权时，通过mongosh连接的用户必须：

Include the --host and --port of the MongoDB server, along with any other options relevant to your deployment.包括MongoDB服务器的--host和--port，以及与部署相关的任何其他选项。

For example, the following operation authenticates to a MongoDB server running with LDAP authentication and authorization:例如，以下操作对运行LDAP身份验证和授权的MongoDB服务器进行身份验证：

mongosh --username alice@dba.example.com --password  --authenticationDatabase '$external' --authenticationMechanism "PLAIN"  --host "mongodb.example.com" --port 27017

If you do not specify the password to the -password command-line option, mongosh prompts for the password.如果没有为-password命令行选项指定密码，mongosh会提示输入密码。

Important重要

The $external argument must be placed in single quotes, not double quotes, to prevent the shell from interpreting $external as a variable.$external参数必须放在单引号中，而不是双引号中，以防止shell将$external解释为变量。

MongoDB Roles for LDAP AuthorizationLDAP授权的MongoDB角色

MongoDB maps each returned group distinguished name (DN) returned by the LDAP query to a role on the admin database.MongoDB将LDAP查询返回的每个返回的组可分辨名称（DN）映射到admin数据库上的一个角色。

If MongoDB acquires a group whose DN exactly matches the name of an existing role, MongoDB grants the authenticated user roles and privileges associated with that role. 如果MongoDB获取的组的DN与现有角色的名称完全匹配，MongoDB将授予经过身份验证的用户角色以及与该角色关联的权限。If MongoDB cannot map any of the returned groups to a role, MongoDB grants no privileges to the user.如果MongoDB无法将任何返回的组映射到角色，则MongoDB不会向用户授予任何权限。

Note注意

LDAP and 和kerberos authentication normally require creating users in the $external database. 身份验证通常需要在$external数据库中创建用户。If you also use LDAP for authorization, you do not need to create users in the $external database. 如果还使用LDAP进行授权，则不需要在$external数据库中创建用户。You only need to create the appropriate roles in the admin database. 您只需要在admin数据库中创建适当的角色。Users still authenticate against the $external database.用户仍然通过$external数据库进行身份验证。

Important重要

If you are using LDAP for authorization and your LDAP group DNs contain RFC4514 escaped sequences, the roles you create in the admin database must also be escaped following RFC4514.如果您使用LDAP进行授权，并且LDAP组DNs包含RFC4514转义序列，则您在admin数据库中创建的角色也必须在RFC4514之后转义。

Example

A database has the following roles configured on the admin database:数据库在admin数据库上配置了以下角色：

{
    role: "CN=dba,CN=Users,DC=example,DC=com",
    privileges: [],
    roles: [ "dbAdminAnyDatabase", "clusterAdmin" ]
}
{
   role: "CN=analytics,CN=Users,DC=example,DC=com"
   privileges: [],
   roles: [
         { role : "read", db : "web_statistics" },
         { role : "read", db : "user_statistics" }
       ]
}

After authenticating a user alice@dba.example.com against the $external database, the MongoDB server performs a query derived from the configured query template to retrieve the groups which include the authenticated user as a member. 验证用户身份后alice@dba.example.com对于$external数据库，MongoDB服务器执行一个从配置的查询模板派生的查询，以检索包括身份验证用户作为成员的组。In this example, the MongoDB server retrieves the following group DNs for the user:在本例中，MongoDB服务器为用户检索以下组DNs：

dn:CN=dba,CN=Users,dc=example,dc=com
dn:CN=admin,CN=Users,dc=example,dc=com

MongoDB maps these group DNs to roles on the admin database. MongoDB将这些组DNs映射到admin数据库上的角色。The first group DN matches the first role, and MongoDB grants the authenticated user its roles and privileges. 第一个组DN与第一个角色匹配，MongoDB向经过身份验证的用户授予其角色和权限。The second group DN does not match to any role on the server, so MongoDB grants no additional permissions.第二个组DN与服务器上的任何角色都不匹配，因此MongoDB不授予其他权限。

A new user bob@analytics.example.com authenticates against the $external database. 新用户bob@analytics.example.com根据$external数据库进行身份验证。The MongoDB server repeats the query process, using the provided username in the query template. MongoDB服务器使用查询模板中提供的用户名重复查询过程。In this example, the MongoDB server retrieves the following group DNs for the user:在本例中，MongoDB服务器为用户检索以下组DNs：

dn:cn=analytics,CN=Users,dc=example,dc=com

MongoDB maps these group DNs to roles on the admin database and grants the authenticated user the roles and privileges of the second role.MongoDB将这些组DNs映射到管理数据库上的角色，并向经过身份验证的用户授予第二个角色的角色和权限。

A new user workstation@guest.example.com authenticates against the $external database. 新用户workstation@guest.example.com根据$external数据库进行身份验证。The MongoDB server repeats the query process, using the provided username in the query template. MongoDB服务器使用查询模板中提供的用户名重复查询过程。In this example, the MongoDB server retrieves the following group DNs for the user:在本例中，MongoDB服务器为用户检索以下组DNs：

dn:cn=guest,CN=Users,dc=example,dc=com

MongoDB maps the group to a role on the admin database and, because no matching roles exist, grants the user no additional permissions.MongoDB将组映射到admin数据库上的一个角色，并且由于不存在匹配的角色，因此不授予用户额外的权限。

←  Collection-Level Access ControlTLS/SSL (Transport Encryption) →