Authenticate Using SASL and LDAP with OpenLDAP

MongoDB Enterprise provides support for proxy authentication of users.This allows administrators to configure a MongoDB cluster toauthenticate users by proxying authentication requests to a specifiedLightweight Directory Access Protocol (LDAP) service.

Note

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.

Considerations

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

Configure saslauthd

LDAP support for user authentication requires proper configuration ofthe saslauthd daemon process as well as the MongoDB server.

Specify the mechanism.

On systems that configure saslauthd with the/etc/sysconfig/saslauthd file, such as Red Hat Enterprise Linux,Fedora, CentOS, and Amazon Linux AMI, set the mechanism MECH toldap:

  1. MECH=ldap

On systems that configure saslauthd with the/etc/default/saslauthd file, such as Ubuntu, set the MECHANISMSoption to ldap:

  1. MECHANISMS="ldap"

Adjust caching behavior.

On certain Linux distributions, saslauthd starts with the cachingof authentication credentials enabled. Until restarted or until thecache expires, saslauthd will not contact the LDAP server tore-authenticate users in its authentication cache. This allowssaslauthd to successfully authenticate users in its cache, even inthe LDAP server is down or if the cached users’ credentials are revoked.

To set the expiration time (in seconds) for the authentication cache, seethe -t option ofsaslauthd.

Configure LDAP Options with OpenLDAP.

If the saslauthd.conf file does not exist, create it.The saslauthd.conf file usually resides in the /etcfolder. If specifying a different file path, see the-O option ofsaslauthd.

To connect to an OpenLDAP server, update the saslauthd.conffile with the following configuration options:

  1. ldap_servers: <ldap uri>
  2. ldap_search_base: <search base>
  3. ldap_filter: <filter>

The ldap_servers specifies the uri of the LDAP server usedfor authentication. In general, for OpenLDAP installed on thelocal machine, you can specify the value ldap://localhost:389or if using LDAP over TLS/SSL, you can specify the valueldaps://localhost:636.

The ldap_search_base specifies distinguished name to whichthe search is relative. The search includes the base or objectsbelow.

The ldap_filter specifies the search filter.

The values for these configuration options should correspond to thevalues specific for your test. For example, to filter on email, specifyldap_filter: (mail=%n) instead.

OpenLDAP Example

A sample saslauthd.conf file for OpenLDAP includes the following content:

  1. ldap_servers: ldaps://ad.example.net
  2. ldap_search_base: ou=Users,dc=example,dc=com
  3. ldap_filter: (uid=%u)

To use this sample OpenLDAP configuration, create users with a uidattribute (login name) and place under the Users organizationalunit (ou) under the domain components (dc) example andcom.

For more information on saslauthd configuration, seehttp://www.openldap.org/doc/admin24/guide.html#Configuringsaslauthd.

Test the saslauthd configuration.

Use testsaslauthd utility to test the saslauthdconfiguration. For example:

  1. testsaslauthd -u testuser -p testpassword -f /var/run/saslauthd/mux
  • 0: OK "Success" indicates successful authentication.
  • 0: NO "authentication failed" indicates a username, password, orconfiguration error.

Modify the file path with respect to the location of thesaslauthd directory on the host operating system.

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.

Configure MongoDB

Add user to MongoDB for authentication.

Add the user to the $external database in MongoDB. To specify theuser’s privileges, assign roles to theuser.

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.

For example, the following adds a user with read-only access tothe records database.

  1. db.getSiblingDB("$external").createUser(
  2.     {
  3.       user : <username>,
  4.       roles: [ { role: "read", db: "records" } ]
  5.     }
  6. )

Add additional principals as needed. For moreinformation about creating and managing users, seeUser Management Commands.

Configure MongoDB server.

To configure the MongoDB server to use the saslauthd instance forproxy authentication, include the following options when starting mongod:

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.

If you use the authorization option to enforceauthentication, you will need privileges to create a user.

Use specific saslauthd socket path.

For socket path of /<some>/<path>/saslauthd, set thesaslauthdPath to /<some>/<path>/saslauthd/mux,as in the following command line example:

  1. mongod --auth --setParameter saslauthdPath=/<some>/<path>/saslauthd/mux --setParameter authenticationMechanisms=PLAIN

Include additional options as required for your configuration. Forinstance, if you wish remote clients to connect to your deploymentor your deployment members are run on different hosts, specify the—bind_ip. For more information, seeLocalhost Binding Compatibility Changes.

Or if using a YAML format configuration file, specify the following settings inthe file:

  1. security:
  2.    authorization: enabled
  3.  
  4. setParameter:
  5.    saslauthdPath: /<some>/<path>/saslauthd/mux
  6.    authenticationMechanisms: PLAIN

Or, if using the older configuration file format:

  1. auth=true
  2. setParameter=saslauthdPath=/<some>/<path>/saslauthd/mux
  3. setParameter=authenticationMechanisms=PLAIN

Use default Unix-domain socket path.

To use the default Unix-domain socket path, set thesaslauthdPath to the empty string "", as in thefollowing command line example:

  1. mongod --auth --setParameter saslauthdPath="" --setParameter authenticationMechanisms=PLAIN

Include additional options as required for your configuration. Forinstance, if you wish remote clients to connect to your deploymentor your deployment members are run on different hosts, specify the—bind_ip. For more information, seeLocalhost Binding Compatibility Changes.

Or if using a YAML format configuration file, specify the following settings inthe file:

  1. security:
  2.    authorization: enabled
  3.  
  4. setParameter:
  5.    saslauthdPath: ""
  6.    authenticationMechanisms: PLAIN

Or, if using the older configuration file format:

  1. auth=true
  2. setParameter=saslauthdPath=""
  3. setParameter=authenticationMechanisms=PLAIN

Include additional options as requiredfor your configuration. For instance, if you wish remote clients toconnect to your deployment or your deployment members are run ondifferent hosts, specify the net.bindIp setting. For moreinformation, see Localhost Binding Compatibility Changes.

Authenticate the user in the mongo shell.

You can authenticate from the command line during connection, orconnect first and then authenticate using db.auth() method.

  • Authenticate during Connection
  • Authenticate after Connection

To authenticate when connecting with the mongo shell,run mongo with the following command-lineoptions, substituting <host> and <user>, andenter your password when prompted:

  1. mongo --host <host> --authenticationMechanism PLAIN --authenticationDatabase '$external' -u <user> -p

Alternatively, connect without supplying credentials and then callthe db.auth() method on the $external database. Specifythe value "PLAIN" in the mechanism field, the user andpassword in the user and pwd fields respectively. Use the defaultdigestPassword value (false) since the server must receive anundigested password to forward on to saslauthd, as in thefollowing example:

Tip

Starting in version 4.2 of the mongo shell, you canuse the passwordPrompt() method in conjunction withvarious user authentication/management methods/commands to promptfor the password instead of specifying the password directly in themethod/command call. However, you can still specify the passworddirectly as you would with earlier versions of themongo shell.

  1. db.getSiblingDB("$external").auth(
  2.    {
  3.      mechanism: "PLAIN",
  4.      user: <username>,
  5.      pwd:  passwordPrompt() // or cleartext password
  6.    }
  7. )

Enter the password when prompted.

The server forwards the password in plain text. In general, use onlyon a trusted channel (VPN, TLS/SSL, trusted wired network). SeeConsiderations.