On this page
New in version 3.4: MongoDB Enterprise supports querying an LDAP server for the LDAP groups to which the authenticated user belongs. MongoDB maps the distinguished names (DN) of each returned group to roles on the
admin database. MongoDB authorizes the user based on the mapped roles and their associated privileges. See LDAP Authorization for more information.
The LDAP Authorization process is summarized below:
Changed in version 3.6.3: To use sessions with
$externalauthentication users (i.e. Kerberos, LDAP, x.509 users), the usernames cannot be greater than 10k bytes.
MongoDB constructs an LDAP query using the
security.ldap.authz.queryTemplateand queries the LDAP server for the authenticated user’s group membership.
MongoDB can use the
security.ldap.userToDNMappingoption to transform the username for supporting the query template.
The LDAP server evaluates the query and returns the list of groups to which the authenticated user belongs.
MongoDB authorizes the user to perform actions on the server by mapping each returned group’s Distinguished Name (DN) into a role on the
admindatabase. If a returned group DN exactly matches the name of an existing role on the
admindatabase, MongoDB grants the user the roles and privileges assigned to that role. See MongoDB Roles for LDAP Authorization for more information.
The client can perform actions on the MongoDB server which require the roles or privileges granted to the authenticated user.
At an interval defined by
ldapUserCacheInvalidationInterval, MongoDB flushes the
$externalcache. Prior to executing subsequent operations performed by externally authorized users, MongoDB re-acquires their group membership from the LDAP server.
A full description of LDAP is beyond the scope of this documentation. This page assumes prior knowledge of LDAP.
This documentation only describes MongoDB LDAP authorization, and does not replace other resources on LDAP. We encourage you to thoroughly familiarize yourself with LDAP and its related subject matter before configuring LDAP authentication.
MongoDB can provide professional services for optimal configuration of LDAP authorization for your MongoDB deployment.
The following authentication mechanisms are compatible with MongoDB LDAP authorization:
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
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.
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. Consider applying the principle of least privilege when configuring MongoDB roles, LDAP groups, or group membership.
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:
- Restart the MongoDB server without authentication and LDAP authorization
- Create a role on the
admindatabase whose name corresponds to the appropriate LDAP group Distinguished Name. When choosing a group DN, consider which group is most appropriate for database administration.
- Restart the MongoDB server with authentication and LDAP authorization
- Authenticate as a user with membership in the group corresponding to the created administrative role.
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
admindatabase named for the user’s LDAP groups, such that the granted roles and privileges are identical to those granted to the non-
If you want to continue allowing access by users not on the
$external database, ensure the
authenticationMechanisms parameter includes
SCRAM-SHA-1. Alternatively, apply the requirements listed above for transitioning those users to LDAP authorization.
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.
You must configure the following settings to use LDAP Authorization:
||Quote-enclosed comma-separated list of LDAP servers in
The identity the MongoDB server binds as when connecting to and executing operations and queries on an LDAP server.
The user specified must have the appropriate privileges to support the LDAP queries generated from the configured
||The password used to bind to an LDAP server when using
|NO, unless using
|NO, unless setting
||Windows MongoDB deployments can use the operating system credentials in place of
||NO, unless replacing