Configure MongoDB with Kerberos Authentication and Active Directory Authorization
On this page
New in version 3.4: MongoDB Enterprise supports querying an LDAP server for the LDAP groups to which an authenticated user belongs. MongoDB maps the LDAP distinguished names (DN) of each returned group to roles on the admin database. MongoDB authorizes the user based on the mapped roles and their associated privileges. See LDAP Authorization for more information.
MongoDB Enterprise supports authentication using a Kerberos service. Kerberos is an industry standard authentication protocol for large client/server systems.
This tutorial describes how to configuring MongoDB to perform authentication through a Kerberos server and authorization through an Active Directory (AD) server via the platform libraries.
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.
Setting up and configuring a Kerberos deployment is beyond the scope of this document. This tutorial assumes you have configured a Kerberos service principal for each mongod and mongos instance in your MongoDB deployment, and you have a valid keytab file for for each mongod and mongos instance.
For replica sets and sharded clusters, ensure that your configuration uses fully qualified domain names (FQDN) rather than IP addresses or unqualified hostnames. You must use the FQDN for GSSAPI to correctly resolve the Kerberos realms and allow you to connect.
To verify MongoDB Enterprise binaries, pass the --version command line option to the mongod or mongos:
mongod --version
In the output from this command, look for the string modules: subscription or modules: enterprise to confirm your system has MongoDB Enterprise.
Considerations
This tutorial explains configuring MongoDB for Kerberos authentication and AD authorization.
To perform this procedure on your own MongoDB server, you must modify the given procedures with respect to your own specific infrastructure, especially Kerberos 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: bob@marketing.example.com
memberOf: CN=marketing,CN=Users,DC=example,DC=com
dn:CN=alice,CN=Users,DC=engineering,DC=example,DC=com
userPrincipalName: alice@engineering.example.com
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: sam@dba.example.com
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: joe@analytics.example.com
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.
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
(Windows only) Assign Service Principal Name to MongoDB Windows Service.
For MongoDB servers running on the Windows operating system, you must use setspn.exe to assign the service principal name (SPN) to the account running the MongoDB service.
setspn.exe -S <service>/<fully qualified domain name> <service account name>
Example
For example, if a mongod runs as a service named mongodb on mongodbserver.example.com with the service account name mongodb_dev@example.com, the command to assign the SPN would look as follows:
setspn.exe -S mongodb/mongodbserver.example.com mongodb_dev@example.com
Note
Windows Server 2003 does not support setspn.exe -S. For complete documentation on setspn.exe, see setspn.exe .
2
(Linux only) Create keytab file for the MongoDB server.
For MongoDB servers running on the Linux platform, you must ensure the server has a copy of the keytab file specific to the MongoDB instance running on that server.
You must grant the Linux user running the MongoDB service read permissions on the keytab file. Take note of the full path of the keytab file location.
3
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