Authenticate and Authorize Users Using Active Directory via Native LDAP

New in version 3.4: MongoDB Enterprise

MongoDB Enterprise provides support via platform LDAP libraries for proxying authentication and authorization requests to a specified Lightweight Directory Access Protocol (LDAP) service such as Active Directory (AD).

This tutorial describes how to configure MongoDB to perform authentication and authorization through an Active Directory (AD) server via the platform libraries.

Changed in version 3.6.3: To use sessions with $external authentication users (i.e. Kerberos, LDAP, x.509 users), the usernames cannot be greater than 10k bytes.

Prerequisites

Important

Thoroughly familiarize yourself with the following subjects before proceeding:

A full description of AD is beyond the scope of this tutorial. This tutorial assumes prior knowledge of AD.

MongoDB supports using SASL mechanisms for binding between the MongoDB server and AD. A full description of SASL, SASL mechanisms, or the specific AD configuration requirements for a given SASL mechanism are beyond the scope of this tutorial. This tutorial assumes prior knowledge of SASL and its related subject matter.

Considerations

This tutorial explains configuring MongoDB for AD authentication and authorization.

To perform this procedure on your own MongoDB server, you must modify the given procedures with respect to your own specific infrastructure, especially Active Directory configurations, constructing AD queries, or managing users.

Transport Layer Security

By default, MongoDB creates a TLS/SSL connection when binding to the AD server. This requires configuring the host of the MongoDB server to have access to the AD server’s Certificate Authority (CA) certificates.

This tutorial provides instructions for the required host configurations.

This tutorial assumes you have access to the AD server’s CA certificates and can create a copy of the certificates on the MongoDB server.

Example Active Directory Schema

This tutorial uses the following example AD objects as the basis for the provided queries, configurations, and output. Each object shows only a subset of the possible attributes.

User Objects

dn:CN=bob,CN=Users,DC=marketing,DC=example,DC=com
userPrincipalName: [email protected]
memberOf: CN=marketing,CN=Users,DC=example,DC=com

dn:CN=alice,CN=Users,DC=engineering,DC=example,DC=com
userPrincipalName: [email protected]
memberOf: CN=web,CN=Users,DC=example,DC=com
memberOf: CN=PrimaryApplication,CN=Users,DC=example,DC=com

dn:CN=sam,CN=Users,DC=dba,DC=example,DC=com
userPrincipalName: [email protected]
memberOf: CN=dba,CN=Users,DC=example,DC=com
memberOf: CN=PrimaryApplication,CN=Users,DC=example,DC=com

dn:CN=joe,CN=Users,DC=analytics,DC=example,DC=com
userPrincipalName: [email protected]
memberof: CN=marketing,CN=Users,DC=example,DC=com

Group Objects

dn:CN=marketing,CN=Users,DC=example,DC=com
member:CN=bob,CN=Users,DC=marketing,DC=example,DC=com
member:CN=joe,CN=Users,DC=analytics,DC=example,DC=com

dn:CN=engineering,CN=Users,DC=example,DC=com
member:CN=web,CN=Users,DC=example,DC=com
member:CN=dba,CN=users,DC=example,DC=com

dn:CN=web,CN=Users,DC=example,DC=com
member:CN=alice,CN=Users,DC=engineering,DC=example,DC=com

dn:CN=dba,CN=Users,DC=example,DC=com
member:CN=sam,CN=Users,DC=dba,DC=example,DC=com

dn:CN=PrimaryApplication,CN=Users,DC=example,DC=com
member:CN=sam,CN=Users,DC=dba,DC=example,DC=com
member:CN=alice,CN=Users,DC=engineering,DC=example,DC=com

Active Directory Credentials

This tutorial uses a username and password for performing queries on the AD server. The credentials provided must have sufficient privileges on the AD server for supporting queries related to security.ldap.userToDNMapping or security.ldap.authz.queryTemplate.

Replica Sets

MongoDB LDAP authorization requires every mongod in the replica set to be on at least MongoDB 3.4.0 or later.

Sharded Clusters

MongoDB LDAP authorization requires every mongod and mongos in the sharded cluster to be on at least MongoDB 3.4.0 or later.

Procedure

1

Configure TLS/SSL for the server running MongoDB

To connect to the AD (AD) server via TLS/SSL, the mongod or mongos require access to the AD server’s Certificate Authority (CA) certificate.

On Linux, specify the AD server’s CA certificates via the TLS_CACERT or TLS_CACERTDIR option in the ldap.conf file.

Your platform’s package manager creates the ldap.conf file while installing MongoDB Enterprise’s libldap dependency. For complete documentation on the configuration file or the referenced options, see ldap.conf .

On Microsoft Windows, load the AD server’s Certificate Authority (CA) certificates with the platform’s credential management tool. The exact credential management tool is Windows version dependent. To use the tool, refer to its documentation for your version of Windows.

If mongod or mongos cannot access to the AD CA files, they cannot create TLS/SSL connections to the Active Directory server.

Optionally, set security.ldap.transportSecurity to none to disable TLS/SSL.

Warning

Setting transportSecurity to none transmits plaintext information, including user credentials, between MongoDB and the AD server.

2

Connect to the MongoDB server.

Connect to the MongoDB server using the mongo shell using the --host and --port options.

mongo --host <hostname> --port <port>

If your MongoDB server currently enforces authentication, you must authenticate to the admin database as a user with role management privileges, such as those provided by userAdmin or userAdminAnyDatabase. Include the appropriate --authenticationMechanism for the MongoDB server’s configured authentication mechanism.

mongo --host <hostname> --port <port> --username <user> --password <pass> --authenticationDatabase="admin" --authenticationMechanism="<mechanism>"

Note

For Windows MongoDB deployments, you should replace mongo with mongo.exe

3

Create user administrative role.

To manage MongoDB users using AD, you need to create at least one role on the admin database that can create and manage roles, such as those provided by userAdmin or userAdminAnyDatabase.

The role’s name must exactly match the Distinguished Name of an AD group. The group must have at least one AD user as a member.

Given the available Active Directory groups,the following operation:

  • Creates a role named for the AD group CN=dba,CN=Users,DC=example,DC=com, and
  • Assigns it the userAdminAnyDatabase role on the admin database.
var admin = db.getSiblingDB("admin")
admin.createRole(
   {
     role: "CN=dba,CN=Users,DC=example,DC=com",
     privileges: [],
     roles: [ "userAdminAnyDatabase" ]
   }
)

You could alternatively grant the userAdmin role for each database the user should have user administrative privileges on. These roles provide the necessary privileges for role creation and management.

Important

Consider applying the principle of least privilege when configuring MongoDB roles, AD groups, or group membership.

4

Create a MongoDB configuration file.

A MongoDB configuration file is a plain-text YAML file with the .conf file extension.

  • If you are upgrading an existing MongoDB deployment, copy the current configuration file and work from that copy.
  • (Linux Only) If this is a new deployment and you used your platform’s package manager to install MongoDB Enterprise, the installation includes the /etc/mongod.conf default configuration file. Use that default configuration file, or make a copy of that file to work from.
  • If no such file exists, create an empty file with the .conf extension and work from that new configuration file.
5

Configure MongoDB to connect to Active Directory.

In the MongoDB configuration file, set security.ldap.servers to the host and port of the AD server. If your AD infrastructure includes multiple AD servers for the purpose