Set up LDAP authentication with SASL¶

This document describes an example configuration suitable only to test out the external authentication functionality in a non-production environment. Use common sense to adapt these guidelines to your production environment.

To learn more about how the authentication works, see LDAP authentication with SASL.

Environment setup and configuration¶

The following components are required:

slapd: OpenLDAP server.
libsasl2 version 2.1.25 or later.
saslauthd: Authentication Daemon (distinct from libsasl2).

The following steps will help you configure your environment:

Assumptions¶

Before we move on to the configuration steps, we assume the following:

You have the LDAP server up and running and have configured users on it. The LDAP server is accessible to the server with Percona Server for MongoDB installed. This document focuses on OpenLDAP server. If you use Microsoft Windows Active Directory, see to the Microsoft Windows Active Directory section for saslauthd configuration.
You must place these two servers behind a firewall as the communications between them will be in plain text. This is because the SASL mechanism of PLAIN can only be used when authenticating and credentials will be sent in plain text.
You have sudo privilege to the server with the Percona Server for MongoDB installed.

Configuring `saslauthd`¶

Install the SASL packages. Depending on your OS, use the following command:
Debian and UbuntuRHEL and derivatives
$ sudo apt install -y sasl2-bin
$ sudo yum install -y cyrus-sasl
NOTE: For Percona Server for MongoDB versions earlier than 4.0.26-21, 4.4.8-9, 4.2.16-17, also install the cyrus-sasl-plain package.
Configure SASL to use ldap as the authentication mechanism.

Note

Back up the original configuration file before making changes.
Debian and UbuntuRHEL and derivatives
Use the following commands to enable the saslauthd to auto-run on startup and to set the ldap value for the --MECHANISMS option:
$ sudo sed -i -e s/^MECH=pam/MECH=ldap/g /etc/sysconfig/saslauthdsudo sed -i -e s/^MECHANISMS="pam"/MECHANISMS="ldap"/g /etc/default/saslauthd $ sudo sed -i -e s/^START=no/START=yes/g /etc/default/saslauthd
Alternatively, you can edit the /etc/default/sysconfig/saslauthd configuration file:
START=yes MECHANISMS="ldap
Specify the ldap value for the --MECH option using the following command:
$ sudo sed -i -e s/^MECH=pam/MECH=ldap/g /etc/sysconfig/saslauthd
Alternatively, you can edit the /etc/sysconfig/saslauthd configuration file:
MECH=ldap
Create the /etc/saslauthd.conf configuration file and specify the settings that saslauthd requires to connect to a local LDAP service:
OpenLDAP serverMicrosoft Windows Active Directory
The following is the example configuration file. Note that the server address MUST match the OpenLDAP installation:
ldap_servers: ldap://localhost ldap_mech: PLAIN ldap_search_base: dc=example,dc=com ldap_filter: (cn=%u) ldap_bind_dn: cn=admin,dc=example,dc=com ldap_password: secret
Note the LDAP password (ldap_password) and bind domain name (ldap_bind_dn). This allows the saslauthd service to connect to the LDAP service as admin. In production, this would not be the case; users should not store administrative passwords in unencrypted files.
In order for LDAP operations to be performed against a Windows Active Directory server, a user record must be created to perform the lookups.

The following example shows configuration parameters for saslauthd to communicate with an Active Directory server:
ldap_servers: ldap://localhost ldap_mech: PLAIN ldap_search_base: CN=Users,DC=example,DC=com ldap_filter: (sAMAccountName=%u) ldap_bind_dn: CN=ldapmgr,CN=Users,DC=<AD Domain>,DC=<AD TLD> ldap_password: ld@pmgr_Pa55word
In order to determine and test the correct search base and filter for your Active Directory installation, the Microsoft LDP GUI Tool can be used to bind and search the LDAP-compatible directory.

Start the saslauthd process and set it to run at restart:

$ sudo systemctl start saslauthd
$ sudo systemctl enable saslauthd

Give write permissions to the /run/saslauthd folder for the mongod. Either change permissions to the /run/saslauthd folder:
```
$ sudo chmod 755 /run/saslauthd
```
Or add the mongod user to the sasl group:
```
$ sudo usermod -a -G sasl mongod
```

Sanity check¶

Verify that the saslauthd service can authenticate against the users created in the LDAP service:

$ testsaslauthd -u christian -p secret  -f /var/run/saslauthd/mux

This should return 0:OK "Success". If it doesn’t, then either the user name and password are not in the LDAP service, or sasaluthd is not configured properly.

Configuring libsasl2¶

The mongod also uses the SASL library for communications. To configure the SASL library, create a configuration file.

The configuration file must be named mongodb.conf and placed in a directory where libsasl2 can find and read it. libsasl2 is hard-coded to look in certain directories at build time. This location may be different depending on the installation method.

In the configuration file, specify the following:

pwcheck_method: saslauthd
saslauthd_path: /var/run/saslauthd/mux
log_level: 5
mech_list: plain

The first two entries (pwcheck_method and saslauthd_path) are required for mongod to successfully use the saslauthd service. The log_level is optional but may help determine configuration errors.

Configuring `mongod` server¶

The configuration consists of the following steps:

Creating a user with the root privileges. This user is required to log in to Percona Server for MongoDB after the external authentication is enabled.
Editing the configuration file to enable the external authentication

Create a root user¶

Create a user with the root privileges in the admin database. If you have already created this user, skip this step. Otherwise, run the following command to create the admin user:

> use admin
switched to db admin
> db.createUser({"user": "admin", "pwd": "$3cr3tP4ssw0rd", "roles": ["root"]})
Successfully added user: { "user" : "admin", "roles" : [ "root" ] }

Enable external authentication¶

Edit the etc/mongod.conf configuration file to enable the external authentication:

security:
  authorization: enabled

setParameter:
  authenticationMechanisms: PLAIN,SCRAM-SHA-1

Restart the mongod service:

$ sudo systemctl restart mongod

Add an external user to Percona Server for MongoDB¶

User authentication is done by mapping a user object on the LDAP server against a user created in the $external database. Thus, at this step, you create the user in the $external database and they inherit the roles and privileges. Note that the username must exactly match the name of the user object on the LDAP server.

Connect to Percona Server for MongoDB and authenticate as the root user.

$ mongo --host localhost --port 27017 -u admin -p '$3cr3tP4ssw0rd' --authenticationDatabase 'admin'

Use the following command to add an external user to Percona Server for MongoDB:

> db.getSiblingDB("$external").createUser( {user : "christian", roles: [ {role: "read", db: "test"} ]} );

Authenticate as an external user in Percona Server for MongoDB¶

When running the mongo client, a user can authenticate against a given database using the following command:

> db.getSiblingDB("$external").auth({ mechanism:"PLAIN", user:"christian", pwd:"secret", digestPassword:false})

Alternatively, a user can authenticate while connecting to Percona Server for MongoDB:

$ mongo --host localhost --port 27017 --authenticationMechanism PLAIN --authenticationDatabase \$external -u christian -p

This section is based on the blog post Percona Server for MongoDB Authentication Using Active Directory by Doug Duncan:

Get expert help¶

If you need assistance, visit the community forum for comprehensive and free database knowledge, or contact our Percona Database Experts for professional support and services.

Community Forum Get a Percona Expert