Authenticate and Authorize Users Using Active Directory via Native LDAP

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.

Connect to the MongoDB server.

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

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

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

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.

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.

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 of replication, specify the host and port of the servers as a comma-delimited list to security.ldap.servers.

You must also enable LDAP authentication by setting security.authorization to enabled and setParameter authenticationMechanisms to PLAIN

security:
  authorization: "enabled"
  ldap:
    servers: "activedirectory.example.net"
setParameter:
  authenticationMechanisms: 'PLAIN'

MongoDB must bind to the AD server to perform queries. By default, MongoDB uses the simple authentication mechanism to bind itself to the AD server.

Alternatively, you can configure the following settings in the configuration file to bind to the AD server using SASL:

• Set security.ldap.bind.method to sasl

• security.ldap.bind.saslMechanisms, specifying a string of comma-separated SASL mechanisms the AD server supports.

This tutorial uses the default simple LDAP authentication mechanism.

Configure LDAP Query Template for authorization.

In the MongoDB configuration file, set security.ldap.authz.queryTemplate to an RFC4516 formatted LDAP query URL template.

In the template, you can use either:

• {USER} placeholder to substitute the authenticated username into the LDAP query URL.

• {PROVIDED_USER} placeholder to substitute the supplied username, i.e. before either authentication or LDAP transformation, into the LDAP query. (Available starting in version 4.2)

security:
  ldap:
    authz:
      queryTemplate:
        "DC=example,DC=com??sub?(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={USER}))"

MongoDB maps each returned group DN to a role on the admin database. For each mapped group DN, if there is an existing role on the admin database whose name exactly matches the DN, MongoDB grants the user the roles and privileges assigned to that role.

The matching rule LDAP_MATCHING_RULE_IN_CHAIN requires providing the full DN of the authenticating user. If users authenticate using a different username format, such as their user principal name, you must transform the incoming usernames into DNs using security.ldap.userToDNMapping.

Optional: Transform incoming usernames for authentication via Active Directory,

If your users authenticate with a username that is not a full LDAP DN, you may need to transform the username to support LDAP authentication or authorization. MongoDB uses the transformed username for both authentication and authorization.

In the MongoDB configuration file, set userToDNMapping to transform the authenticating user's provided username into an AD DN to support the queryTemplate.

security:
  ldap:
    userToDNMapping:
      '[
         {
            match : "(.+)",
            ldapQuery: "DC=example,DC=com??sub?(userPrincipalName={0})"
         }
    ]'

You must modify the given sample configuration to match your deployment. For example, the ldapQuery base DN must match the base DN which contains your user entities. Other modifications may be necessary to support your AD deployment.

DC=example,DC=com??sub?(userPrincipalName=alice@ENGINEERING.EXAMPLE.COM)

Configure query credentials.

MongoDB requires credentials for performing queries on the AD server.

Configure the following settings in the configuration file:

• security.ldap.bind.queryUser, specifying the Active Directory user the mongod or mongos binds as for performing queries on the AD server.

• security.ldap.bind.queryPassword, specifying the password for the specified queryUser.

security:
  ldap:
    bind:
      queryUser: "mongodbadmin@dba.example.com"
      queryPassword: "secret123"

On Windows MongoDB servers, you can set security.ldap.bind.useOSDefaults to true to use the credentials of the OS user instead of queryUser and queryPassword.

The queryUser must have permission to perform all LDAP queries on behalf of MongoDB.

Optional: Add additional configuration settings.

Add any additional configuration options required for your deployment. For example, you can specify your desired storage.dbPath or change the default net.port number.

mongod and mongos bind to localhost by default. If the members of your deployment are run on different hosts or if you wish remote clients to connect to your deployment, you must specify the net.bindIp setting.

Start the MongoDB server with Active Directory authentication and authorization.

Start the MongoDB server with the --config option, specifying the path to the configuration file created during this procedure. If the MongoDB server is currently running, make the appropriate preparations to stop the server.

mongod --config <path-to-config-file>

Windows MongoDB deployments must use exe instead of mongod.

Connect to the MongoDB server.

Connect to the MongoDB server, authenticating as a user whose direct or transitive group membership corresponds to a MongoDB role on the admin database with userAdmin, userAdminAnyDatabase, or a custom role with equivalent privileges.

Use mongosh to authenticate to the MongoDB server, set the following options:

• --host with the hostname of the MongoDB server

• --port with the port of the MongoDB server

• --username to the user's username

• --password to the user's password

• --authenticationMechanism to 'PLAIN'

• --authenticationDatabase to '$external'

mongosh --username sam@DBA.EXAMPLE.COM --password  --authenticationMechanism 'PLAIN' --authenticationDatabase '$external' --host <hostname> --port <port>

Windows MongoDB deployments must use mongo.exe instead of mongosh.

Given the configured Active Directory users, the user authenticates successfully and receives the appropriate permissions.

Create roles for mapping returned AD groups.

For each group on the AD server you wish to use for MongoDB authorization, you must create a matching role on the MongoDB server's admin database.

db.getSiblingDB("admin").createRole(
   {
     role: "CN=PrimaryApplication,CN=Users,DC=example,DC=com",
     privileges: [],
     roles: [
       { role: "readWrite", db: "PrimaryApplication" }
     ]
   }
)

Transition existing users from $external to the ActiveDirectory server

If upgrading an existing installation with users configured on the $external database, you must meet the following requirements for each user to ensure access after configuring MongoDB for AD authentication and authorization:

• User has a corresponding user object on the AD server.

• User has membership in the appropriate groups on the AD server.

• MongoDB contains the roles on the admin database named for the user's AD groups, such that the authorized user retains its privileges.

{
  user : "joe@ANALYTICS.EXAMPLE.COM",
  roles: [
    { role : "read", db : "web_analytics" },
    { role : "read", db : "PrimaryApplication" }
  ]
}

db.getSiblingDB("admin").createRole(
   {
     role: "CN=marketing,CN=Users,DC=example,DC=com",
     privileges: [],
     roles: [
       { role: "read", db: "web_analytics" }
       { role: "read", db: "PrimaryApplication" }
     ]
   }
)

If you want to continue allowing users on non-$external databases to access MongoDB, you must include SCRAM authentication mechanism (e.g. SCRAM-SHA-1 and/or SCRAM-SHA-256) in the setParameter authenticationMechanisms configuration option. For example:

setParameter:
  authenticationMechanisms: "PLAIN,SCRAM-SHA-1,SCRAM-SHA-256"

Alternatively, transition non-$external users to AD by following the above procedure.