LDAP Authorization

New in version 3.4: MongoDB Enterprise supportsquerying an LDAP server for the LDAP groups to which the authenticated userbelongs. MongoDB maps the distinguished names (DN) of each returned groupto roles on the admin database. MongoDB authorizes theuser based on the mapped roles and their associated privileges. SeeLDAP Authorization for more information.

The LDAP Authorization process is summarized below:

• A client connects to MongoDB and performs authentication with anyauthentication mechanism thatsupports external authentication.

Changed in version 3.6.3: To use sessions with $external authentication users (i.e.Kerberos, LDAP, x.509 users), the usernames cannot be greaterthan 10k bytes.

• MongoDB binds to the LDAP server specified with security.ldap.serversusing the credentials specified with security.ldap.bind.queryUser andsecurity.ldap.bind.queryPassword.

MongoDB uses simple binding by default, but can use sasl bindinginstead if configured in security.ldap.bind.method andsecurity.ldap.bind.saslMechanisms.

• MongoDB constructs an LDAP query using thesecurity.ldap.authz.queryTemplate and queries the LDAP server forthe authenticated user’s group membership.

MongoDB can use the security.ldap.userToDNMapping option totransform the username for supporting the query template.

• The LDAP server evaluates the query and returns the list ofgroups to which the authenticated user belongs.

• MongoDB authorizes the user to perform actions on the server by mappingeach returned group’s Distinguished Name (DN) into a role on the admin database. If a returned group DN exactlymatches the name of an existing role on the admin database, MongoDBgrants the user the roles and privileges assigned to that role. SeeMongoDB Roles for LDAP Authorization for more information.

• The client can perform actions on the MongoDB server which require the rolesor privileges granted to the authenticated user.

• At an interval defined by ldapUserCacheInvalidationInterval,MongoDB flushes the $external cache. Prior to executingsubsequent operations performed by externally authorized users, MongoDBre-acquires their group membership from the LDAP server.

Considerations

A full description of LDAP is beyond the scope of this documentation. Thispage assumes prior knowledge of LDAP.

This documentation only describes MongoDB LDAP authorization, and does notreplace other resources on LDAP. We encourage you to thoroughly familiarizeyourself with LDAP and its related subject matter before configuring LDAPauthentication.

MongoDB can provide professional services for optimalconfiguration of LDAP authorization for your MongoDB deployment.

Compatible Authentication Mechanism

The following authentication mechanisms are compatible with MongoDB LDAPauthorization:

• LDAP Proxy Authentication
• Kerberos Authentication
• x.509

Connection Pool

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

• Uses connection pooling if run:

  • on Windows or
  • on Linux where MongoDB Enterprise binaries are linked againstlibldap_r.

• Does not use connection pooling if run:

  • on Linux where MongoDB Enterprise binaries are linked againstlibldap.

Tip

To allow concurrent authentication commands for LDAP users, youmay wish to link to libldap_r. For assistance, contactsupport.

To change the connection pooling behavior, update theldapUseConnectionPool parameter.

libldap and libldap_r

For MongoDB 4.2 (and 4.0.9) Enterprise binaries linked againstlibldap (such as when running on RHEL), access to thelibldap is synchronized, incurring some performance/latencycosts.

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

To avoid the automatic synchronization with libldap, you maywish to link to libldap_r. Contact support forassistance.

User Management

With LDAP authorization, user creation and management occurs on the LDAPserver. MongoDB requires creation of roles on the admindatabase, with the name of each role exactly matching a LDAP groupDistinguished 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 groupmembership corresponds to a admin database role with role administrationprivileges, such as those provided by userAdmin. Create or updateroles corresponding to LDAP group DNs such that users with membership in thatgroup receive the appropriate roles and privileges.

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

Important

When configuring a role for a corresponding LDAP Group, remember that _all_users with membership in that group can receive the configured roles andprivileges. Consider applying the principle of least privilege whenconfiguring MongoDB roles, LDAP groups, or group membership.

If no role with role administration privileges exists AND nonon-$external user with these privileges exists, you effectively cannotperform user management, as no new or existing roles can be altered to reflectadditions 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 admin database whose name corresponds to theappropriate 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 thecreated 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 useron 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 LDAPgroups, such that the granted roles and privileges are identical to thosegranted to the non-$external user.

If you want to continue allowing access by users not on the$external database, ensure theauthenticationMechanisms parameter includesSCRAM-SHA-1 and/or SCRAM-SHA-256 as appropriate. Alternatively,apply the requirements listed above for transitioning those users toLDAP authorization.

Replica Sets

For replica sets, configure LDAP authorization on thesecondary and arbiter members first before configuring theprimary. 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 membersfor write availability.

Sharded Clusters

In sharded clusters, you must configure LDAPauthorization on the config servers for cluster-levelusers. You can optionally configure LDAP authorization on eachshard for shard-local users.

Configuration

You must configure the following settings to use LDAP Authorization:

To use LDAP for authorization via operating system libraries, specify thefollowing settings as a part of your mongod or mongosconfiguration file:

LDAP Query Template

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

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

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

Example

The following query template returns any groups listed in theLDAP user object’s memberOf attribute. This query assumes the memberOfattribute exists - your specific LDAP deployment may use a different attributeor methodology for tracking group membership. This query also assumesthe user authenticates using their full LDAP DN as their username.

"{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 athe DNs which this entity is member of.

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

MongoDB currently ignores any extensions specified in the LDAP query.

Important

A full description of RFC4516 or LDAP query URL construction is out ofscope for this documentation.

Tutorials

The following tutorials contain procedures for connecting to an LDAP servervia the Operating System LDAP libraries:

• Authenticate and Authorize Users Using Active Directory via Native LDAP
• Configure MongoDB with Kerberos Authentication and Active Directory Authorization

Connecting to a MongoDB server using LDAP Authorization

When using LDAP for authorization, users connecting via the mongoshell must:

• set —authenticationDatabase to $external.

• set —authenticationMechanism to the appropriate authenticationmechanism.

If using LDAP authentication, set this to PLAIN.

If using Kerberos authentication, set this toGSSAPI.

If using x.509, set this to MONGODB-X.509.

• set —username to a username that respects thesecurity.ldap.authz.queryTemplate, or any configuredsecurity.ldap.userToDNMapping template.

• set —password to the appropriate password.

Include the —host and —port of the MongoDB server,along with any other options relevant to your deployment.

For example, the following operation authenticates to a MongoDB server runningwith LDAP authentication and authorization:

mongo --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, the mongo shellprompts for the password.

Important

The $external argument must be placed in single quotes, notdouble quotes, to prevent the shell from interpreting $externalas a variable.

MongoDB Roles for LDAP Authorization

MongoDB maps each returned group distinguished name (DN) returned bythe LDAP query to arole on the admin database.

If MongoDB acquires a group whose DN exactly matches the name of anexisting role, MongoDB grants the authenticated user roles andprivileges associated with that role. If MongoDBcannot map any of the returned groups to a role, MongoDB grants noprivileges to the user.

Note

LDAP and kerberosauthentication normally require creating users in the $externaldatabase. If you also use LDAP for authorization, you do not need tocreate users in the $external database. You only need to create theappropriate roles in the admin database. Users still authenticateagainst the $external database.

Important

If you are using LDAP for authorization and your LDAP group DNscontain RFC4514 escapedsequences, the roles you create in the admin database must alsobe escaped following RFC4514.

Example

A database has the following roles configured on the admin database:

{
    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 fromthe configured query template to retrieve the groups which includethe authenticated user as a member. In this example, the MongoDB serverretrieves the following group DNs for the user:

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. The firstgroup DN matches the first role, and MongoDB grants the authenticated userits roles and privileges. The second group DN does not match to any role onthe server, so MongoDB grants no additional permissions.

A new user bob@analytics.example.com authenticates against the$external database. The MongoDB server repeats the query process, usingthe provided username in the query template. In this example, the MongoDBserver retrieves the following group DNs for the user:

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

MongoDB maps these group DNs to roles on the admin database and grantsthe authenticated user the roles and privileges of the second role.

A new user workstation@guest.example.com authenticates against the$external database. The MongoDB server repeats the query process, usingthe provided username in the query template. In this example, the MongoDBserver retrieves the following group DNs for the user:

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

MongoDB maps the group to a role on the admin database and, because nomatching roles exist, grants the user no additional permissions.