LDAP Authorization¶

Compatible Authentication Mechanism¶

The following authentication mechanisms are compatible with MongoDB LDAP authorization:

• LDAP Proxy Authentication
• Kerberos Authentication
• x.509

Connection Pool¶

Starting in version 4.2.0, when connecting to the LDAP server for authentication/authorization, MongoDB, by default:

• Uses connection pooling if run:
  • on Windows or
  • on Linux where MongoDB Enterprise binaries are linked against libldap_r.
• Does not use connection pooling if run:
  • on Linux where MongoDB Enterprise binaries are linked against libldap.

To change the connection pooling behavior, update the ldapUseConnectionPool parameter.

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.

For MongoDB 4.2 (and 4.0.9) Enterprise binaries linked against libldap_r, there is no change in behavior from earlier MongoDB versions.

User Management¶

With LDAP authorization, user creation and management occurs on the LDAP server. MongoDB requires creation of roles on the admin database, with the name of each role exactly matching a LDAP group Distinguished Name (DN). This is in contrast to MongoDB managed authorization, which requires creating users on the $external database.

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. Create or update roles corresponding to LDAP group DNs such that users with membership in that group receive the appropriate roles and privileges.

For example, an LDAP group for database administrators might have a role with administrative roles and privileges. An LDAP group for marketing or analytics users may have a role with only have read privileges on certain databases.

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.

To remedy a scenario where you cannot manage roles on the MongoDB server, perform the following procedure:

1. Restart the MongoDB server without authentication and LDAP authorization
2. Create a role on the admin database whose name corresponds to the appropriate LDAP group Distinguished Name. When choosing a group DN, consider which group is most appropriate for database administration.
3. Restart the MongoDB server with authentication and LDAP authorization
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. 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:

• User has a corresponding user object on the LDAP server
• User object has membership in the appropriate LDAP groups
• 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.

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. Alternatively, apply the requirements listed above for transitioning those users to LDAP authorization.

Replica Sets¶

For replica sets, configure LDAP authorization on the secondary and arbiter members first before configuring the primary. 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. You can optionally configure LDAP authorization on each shard for shard-local users.

LDAP Query Template¶

MongoDB uses the security.ldap.authz.queryTemplate to create an RFC4516 formatted LDAP query URL. In the template, you can use either:

• {USER} placeholder to substitute the authenticated username into the LDAP query URL. If MongoDB transformed the username using userToDNMapping, MongoDB replaces the {USER} token with the transformed username when constructing the LDAP query URL.
• {PROVIDED_USER} placeholder to substitute the supplied username, i.e. before either authentication or LDAP transformation, into the LDAP query.

Design the query template to retrieve the user’s groups.

"{USER}?memberOf?base"

The LDAP query URL must conform to the format defined in RFC4516:

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

Consider the definition of each component, as quoted from RFC4516:

The ``dn`` is an LDAP Distinguished Name using the string format described
in `RFC4514 <https://tools.ietf.org/html/rfc4514>`_. It identifies the base
object of the LDAP search or the target of a non-search operation.

The ``attributes`` construct is used to indicate which attributes should be
returned from the entry or entries.

The ``scope`` construct is used to specify the scope of the search to perform
in the given LDAP server. 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. It has the format specified
in [RFC4515].

The ``extensions`` construct provides the LDAP URL with an extensibility
mechanism, allowing the capabilities of the URL to be extended in the
future.

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

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

MongoDB currently ignores any extensions specified in the LDAP query.