LDAP Proxy Authentication

MongoDB Enterprise supportsproxying authentication requests to a Lightweight Directory Access Protocol(LDAP) service.

MongoDB supports simple and SASL binding to LDAP servers:

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 authentication, 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 authentication for your MongoDB deployment.

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.

saslauthd and Directory Permissions

Important

The parent directory of the saslauthd Unix domain socket filespecified to security.sasl.saslauthdSocketPath or—setParameter saslauthdPath must grantread and execute (r-x) permissions for either:

• The user starting the mongod ormongos, or
• A group to which that user belongs.

The mongod or mongos cannot successfully authenticate viasaslauthd without the specified permission on the saslauthddirectory and its contents.

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.

Managing LDAP Users on the MongoDB server

User management requires managing users both on the LDAP server and theMongoDB server. For each user authenticating via LDAP, MongoDB requires a useron the $external database whose name exactly matches the authenticationusername. Changes to a user on the LDAP server may require changes to thecorresponding MongoDB $external user.

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.

Example

A user authenticates as sam@dba.example.com. The MongoDB serverbinds to the LDAP server and authenticates the user, respecting anyusername transformations.On successful authentication, the MongoDB server then checks the$external database for a user sam@dba.example.com andgrants the authenticated user the roles and privileges associated tothat user.

To manage users on the MongoDB server, you must authenticate as an LDAP userwhose corresponding MongoDB $external user has user administrativeprivileges on the $external database, such as those provided byuserAdmin.

Important

If no $external users have user administrative privileges on$external database, you cannot perform user management for LDAPauthentication. This scenario may occur if you configure users prior toenabling LDAP authentication, but do not create the appropriate useradministrators.

Managing existing non-LDAP users

If there are existing users not on the $external database, you must meetthe following requirements for each user to ensure continued access:

• User has a corresponding user object on the LDAP server
• User exists on the $external database with equivalent roles andprivileges

If you want to continue allowing access by users not on the$external database, you must configure setParameterauthenticationMechanisms to include SCRAM-SHA-1 and/orSCRAM-SHA-256 as appropriate. Users must then specify—authenticationMechanism SCRAM-SHA-1 orSCRAM-SHA-256 when authenticating.

Deploying LDAP authentication on a replica set

For replica sets, configure LDAP authentication onsecondary 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.

Deploying LDAP authentication on a sharded cluster

In sharded clusters, you must configure LDAPauthentication on the config servers and eachmongos for cluster-level users. You can optionally configure LDAPauthorization on each shard for shard-local users.

LDAP Authentication via the Operating System LDAP libraries

New in version 3.4.

The LDAP authentication via OS libraries process is summarized below:

• A client authenticates to MongoDB, providing a user’s credentials.

• If the username requires mapping to an LDAP DN prior to binding against theLDAP server, MongoDB can apply transformations based on the configuredsecurity.ldap.userToDNMapping setting.

• MongoDB binds to an LDAP server specified insecurity.ldap.servers using the provided username or, if atransformation was applied, the transformed username.

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

If a transformation requires querying the LDAP server, or if the LDAPserver disallows anonymous binds, MongoDB uses the username and passwordspecified to security.ldap.bind.queryUser andsecurity.ldap.bind.queryPassword to bind to the LDAP serverbefore attempting to authenticate the provided user credentials.

• The LDAP server returns the result of the bind attempt to MongoDB. Onsuccess, MongoDB attempts to authorize the user.

• The MongoDB server attempts to map the username to a user on the$external database, assigning the user any roles or privilegesassociated to a matching user. If MongoDB cannot find a matching user,authentication fails.

• The client can perform those actions for which MongoDB granted theauthenticated user roles or privileges.

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

LDAP Authentication via saslauthd

Warning

MongoDB Enterprise for Windows does not support binding viasaslauthd.

Considerations

• Linux MongoDB servers support binding to an LDAP server via thesaslauthd daemon.
• Use secure encrypted or trusted connections between clients and theserver, as well as between saslauthd and the LDAP server. TheLDAP server uses the SASL PLAIN mechanism, sending and receivingdata in plain text. You should use only a trusted channel such asa VPN, a connection encrypted with TLS/SSL, or a trusted wirednetwork.

Configuration

To configure the MongoDB server to bind to the LDAP server using viasaslauthd, usethe following command line options:

• —auth to enable access control,
• —authenticationMechanisms set to PLAIN, and
• —saslauthdPath parameter set to the path to the Unix-domain Socketof the saslauthd instance.

Or, if using the YAML configuration file, use the following settings:

• security.authorization set to enabled,
• setParameter.authenticationMechanisms set to PLAIN, and
• setParameter.saslauthdPath set to the path to theUnix-domain Socket of the saslauthd instance.

You need to create or update the saslauthd.conf file with the parametersappropriate for your LDAP server. Documenting saslauthd.conf is outof scope for this documentation.

Important

The parent directory of the saslauthd Unix domain socket filespecified to security.sasl.saslauthdSocketPath or—setParameter saslauthdPath must grantread and execute (r-x) permissions for either:

• The user starting the mongod ormongos, or
• A group to which that user belongs.

The mongod or mongos cannot successfully authenticate viasaslauthd without the specified permission on the saslauthddirectory and its contents.

The following tutorials provide basicinformation on configuring saslauthd.conf to work with two popularLDAP services:

• Authenticate Using SASL and LDAP with OpenLDAP
• Authenticate Using SASL and LDAP with ActiveDirectory

Please see the documentation for saslauthd as well as your specificLDAP service for guidance.

Connect to a MongoDB server via LDAP authentication

To authenticate to a MongoDB server via LDAP authentication, usedb.auth() on the $external database with the followingparameters: