Self-Managed LDAP Proxy Authentication (original) (raw)

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

MongoDB supports simple and SASL binding to LDAP servers:

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.

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 againstlibldap_r.
• Does not use connection pooling if run:
  • on Linux where MongoDB Enterprise binaries are linked againstlibldap.

To change the connection pooling behavior, update theldapUseConnectionPool parameter.

Important

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

For MongoDB 4.2 Enterprise binaries linked againstlibldap_r, there is no change in behavior from earlier MongoDB versions.

When using LDAP authentication without LDAP authorization, user management requires managing users both on the LDAP server and the MongoDB server. For each user authenticating via LDAP, MongoDB requires a user on the $external database whose name exactly matches the authentication username. Changes to a user on the LDAP server may require changes to the corresponding MongoDB$external user.

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.

Example

A user authenticates as sam@dba.example.com. The MongoDB server binds 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 and grants the authenticated user the roles and privileges associated to that user.

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 byuserAdmin.

Important

If no $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 administrators.

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 $external database with equivalent roles and privileges

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

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 members for write availability.

In sharded clusters, you must configure LDAP authentication on the config servers and eachmongos 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:

1. A client authenticates to MongoDB, providing a user's credentials.
2. If the username requires mapping to an LDAP DN prior to binding against the LDAP server, MongoDB can apply transformations based on the configuredsecurity.ldap.userToDNMapping setting.
3. MongoDB binds to an LDAP server specified insecurity.ldap.servers using the provided username or, if a transformation was applied, the transformed username.
   MongoDB uses simple binding by default, but can also use sasl binding if configured in security.ldap.bind.method andsecurity.ldap.bind.saslMechanisms.
   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.queryUser andsecurity.ldap.bind.queryPassword to bind to the LDAP server before attempting to authenticate the provided user credentials.
4. The LDAP server returns the result of the bind attempt to MongoDB. On success, MongoDB attempts to authorize the user.
5. The MongoDB server attempts to map the username to a user on the$external database, assigning the user any roles or privileges associated to a matching user. If MongoDB cannot find a matching user, authentication fails.
6. The client can perform those actions for which MongoDB granted the authenticated user roles or privileges.

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

Warning

MongoDB Enterprise for Windows does not support binding viasaslauthd.

• Linux MongoDB servers support binding to an LDAP server via thesaslauthd daemon.
• Use secure encrypted or trusted connections between clients and the server, as well as between saslauthd and the LDAP server. The LDAP server uses the SASL PLAIN mechanism, 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 viasaslauthd, start the mongod using either the following command line options or the following configuration file settings:

• --auth to enable access control,
• --setParameter with theauthenticationMechanisms set to PLAIN, and
• --setParameter with thesaslauthdPath parameter set to the path to the Unix-domain Socket of the saslauthd instance. Specify an empty string "" to use the default Unix-domain socket path.

Include any other command line options required for your deployment. For complete documentation on mongodcommand line options, see mongod.

• security.authorization set to enabled,
• setParameter with theauthenticationMechanisms parameter set toPLAIN, and
• setParameter with the saslauthdPath set to the path to the Unix-domain Socket of the saslauthd instance. Specify an empty string "" to use the default Unix-domain socket path.

Include any other configuration file settings required for your deployment. For complete documentation on configuration files, seeYAML configuration file.

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.

Important

The following tutorials provide basic information on configuring saslauthd.conf to work with two popular LDAP services:

• Authenticate Using Self-Managed SASL and LDAP with OpenLDAP
• Authenticate Using Self-Managed SASL and LDAP with ActiveDirectory

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

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