On this page
MongoDB Enterprise supports proxying authentication requests to a Lightweight Directory Access Protocol (LDAP) service.
MongoDB supports simple and SASL binding to LDAP servers:
Operating system libraries
Starting in version 3.4, MongoDB supports binding to an LDAP server via operating system libraries.
This allows MongoDB servers on Linux and Windows to use an LDAP server for authentication.
In earlier versions, MongoDB on Microsoft Windows cannot connect to LDAP servers.
MongoDB servers on Linux supports binding to an LDAP server via
Not available for MongoDB on Windows.
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 authentication, 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 authentication for your MongoDB deployment.
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
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
For MongoDB 4.2 (and 4.0.9) Enterprise binaries linked against
libldap_r, there is no change in behavior from earlier MongoDB
User management requires managing users both on the LDAP server and the
MongoDB server. For each user authenticating via LDAP, MongoDB requires a user
$external database whose name exactly matches the authentication
username. Changes to a user on the LDAP server may require changes to the
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.
A user authenticates as
firstname.lastname@example.org. The MongoDB server
binds to the LDAP server and authenticates the user, respecting any
On successful authentication, the MongoDB server then checks the
$external database for a user
grants the authenticated user the roles and privileges associated to
To manage users on the MongoDB server, you must authenticate as an LDAP user
whose corresponding MongoDB
$external user has user administrative
privileges on the
$external database, such as those provided by
$external users have user administrative privileges on
$external database, you cannot perform user management for LDAP
authentication. This scenario may occur if you configure users prior to
enabling LDAP authentication, but do not create the appropriate user
If there are existing users not on the
$external database, you must meet
the following requirements for each user to ensure continued access:
- User has a corresponding user object on the LDAP server
- User exists on the
$externaldatabase with equivalent roles and privileges
If you want to continue allowing access by users not on the
$external database, you must configure
authenticationMechanisms to include
SCRAM-SHA-256 as appropriate. Users must then specify
--authenticationMechanism SCRAM-SHA-1 or
SCRAM-SHA-256 when authenticating.
For replica sets, configure LDAP authentication on 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.
In sharded clusters, you must configure LDAP
authentication on the config servers and each
mongos for cluster-level users. You can optionally configure LDAP
authorization on each shard for shard-local users.
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 the
LDAP server, MongoDB can apply transformations based on the configured
MongoDB binds to an LDAP server specified in
security.ldap.serversusing the provided username or, if a transformation was applied, the transformed username.
If a transformation requires querying the LDAP server, or if the LDAP server disallows anonymous binds, MongoDB uses the username and password specified to
security.ldap.bind.queryPasswordto bind to the LDAP server before attempting to authenticate the provided user credentials.
- The LDAP server returns the result of the bind attempt to MongoDB. On success, MongoDB attempts to authorize the user.
- The MongoDB server attempts to map the username to a user on the
$externaldatabase, assigning the user any roles or privileges associated to a matching user. If MongoDB cannot find a matching user, authentication fails.
- The client can perform those actions for which MongoDB granted the authenticated user roles or privileges.
Quote-enclosed comma-separated list of LDAP servers in
NO, unless using
NO, unless setting
The LDAP entity, identified by its distinguished name (DN) or SASL name, with which the MongoDB server authenticates, or binds, when connecting to an LDAP server.
The user specified must have the appropriate privileges to execute queries on the LDAP server.
NO, unless specifying a query as part of a
The password used to authenticate to an LDAP server when using
NO, unless specifying
Clients may authenticate using a username whose format is incompatible
with the format expected by the configured
NO, unless client authenticate using usernames that require transformation.
MongoDB Enterprise for Windows does not support binding via
- Linux MongoDB servers support binding to an LDAP server via the
- Use secure encrypted or trusted connections between clients and the
server, as well as between
saslauthdand the LDAP server. The LDAP server uses the
SASL PLAINmechanism, sending and receiving data in plain text. You should use only a trusted channel such as a VPN, a connection encrypted with TLS/SSL, or a trusted wired network.
To configure the MongoDB server to bind to the LDAP server using via
saslauthd, start the
mongod using either
the following command line options or the following configuration
You need to create or update the
saslauthd.conf file with the parameters
appropriate for your LDAP server. Documenting
saslauthd.conf is out
of scope for this documentation.
The following tutorials provide basic
information on configuring
saslauthd.conf to work with two popular
Please see the documentation for
saslauthd as well as your specific
LDAP service for guidance.
To authenticate to a MongoDB server via LDAP authentication, use
db.auth() on the
$external database with the following
The username to authenticate as.
The password to authenticate with.