Configure Self-Managed MongoDB with Kerberos Authentication on Linux

Start mongod without Kerberos.

For the initial addition of Kerberos users, start mongod without Kerberos support.

If a Kerberos user is already in MongoDB and has the privileges required to create a user, you can start mongod with Kerberos support.

Include additional settings as appropriate to your deployment.

Connect to mongod.

Connect mongosh to the mongod instance. If mongod has --auth enabled, ensure you connect with the privileges required to create a user.

Add Kerberos Principal(s) to MongoDB.

Add a Kerberos principal, <username>@<KERBEROS REALM> or <username>/<instance>@<KERBEROS REALM>, to MongoDB in the $external database. Specify the Kerberos realm in all uppercase. The $external database allows mongod to consult an external source (e.g. Kerberos) to authenticate. To specify the user's privileges, assign roles to the user.

To use Client Sessions and Causal Consistency Guarantees with $external authentication users (Kerberos, LDAP, or x.509 users), the usernames cannot be greater than 10k bytes.

The following example adds the Kerberos principal application/reporting@EXAMPLE.NET with read-only access to the records database:

use $external
db.createUser(
   {
     user: "application/reporting@EXAMPLE.NET",
     roles: [ { role: "read", db: "records" } ]
   }
)

Add additional principals as needed. For every user you want to authenticate using Kerberos, you must create a corresponding user in MongoDB. For more information about creating and managing users, see User Management Commands.

Start mongod with Kerberos support.

To start mongod with Kerberos support, set the environmental variable KRB5_KTNAME to the path of the keytab file and the mongod parameter authenticationMechanisms to GSSAPI in the following form:

env KRB5_KTNAME=<path to keytab file> \
mongod \
--setParameter authenticationMechanisms=GSSAPI \
<additional mongod options>

Include additional options as required for your configuration. For instance, if you wish remote clients to connect to your deployment or your deployment members are run on different hosts, specify the --bind_ip.

For example, the following starts a standalone mongod instance with Kerberos support:

env KRB5_KTNAME=/opt/mongodb/mongod.keytab \
/opt/mongodb/bin/mongod --auth \
--setParameter authenticationMechanisms=GSSAPI \
--dbpath /opt/mongodb/data --bind_ip localhost,<hostname(s)|ip address(es)>

The path to your mongod as well as your keytab file may differ. The keytab file must be only accessible to the owner of the mongod process.

With the official .deb or .rpm packages, you can set the KRB5_KTNAME in a environment settings file. See KRB5_KTNAME for details.

Connect mongosh to mongod and authenticate.

Connect mongosh client as the Kerberos principal application/reporting@EXAMPLE.NET. Before connecting, you must have used Kerberos's kinit program to get credentials for application/reporting@EXAMPLE.NET.

You can connect and authenticate from the command line.

mongosh --host hostname.example.net --authenticationMechanism=GSSAPI --authenticationDatabase='$external' --username application/reporting@EXAMPLE.NET

If you are connecting to a system whose hostname matches the Kerberos name, ensure that you specify the fully qualified domain name (FQDN) for the --host option, rather than an IP address or unqualified hostname.

If you are connecting to a system whose hostname does not match the Kerberos name, first connect mongosh to the mongod, and then from mongosh, use the db.auth() method to authenticate in the $external database.

use $external
db.auth( { mechanism: "GSSAPI", user: "application/reporting@EXAMPLE.NET" } )