Security >
Security Tutorials >
Authentication Mechanisms >
Configure MongoDB with Kerberos Authentication on Windows

Configure MongoDB with Kerberos Authentication on Windows¶

On this page

Overview
Prerequisites
Procedures
Additional Considerations

New in version 2.6.

Overview¶

MongoDB Enterprise supports authentication using a Kerberos service. Kerberos is an industry standard authentication protocol for large client/server system. Kerberos allows MongoDB and applications to take advantage of existing authentication infrastructure and processes.

Prerequisites¶

Setting up and configuring a Kerberos deployment is beyond the scope of this document. This tutorial assumes have configured a Kerberos service principal for each mongod.exe and mongos.exe instance.

Procedures¶

1

Start `mongod.exe` without Kerberos.¶

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

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

2

Connect to `mongod`.¶

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

3

Add Kerberos Principal(s) to MongoDB.¶

Add a Kerberos principal, <username>@<KERBEROS REALM>, to MongoDB in the $external database. Specify the Kerberos realm in ALL UPPERCASE. The $external database allows mongod.exe to consult an external source (e.g. Kerberos) to authenticate. To specify the user’s privileges, assign roles to the user.

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

use $external
db.createUser(
   {
     user: "[email protected]",
     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.

4

Start `mongod.exe` with Kerberos support.¶

You must start mongod.exe as the service principal account.

To start mongod.exe with Kerberos support, set the mongod.exe parameter authenticationMechanisms to GSSAPI:

mongod.exe --setParameter authenticationMechanisms=GSSAPI <additional mongod.exe options>

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

mongod.exe --auth --setParameter authenticationMechanisms=GSSAPI

Modify or include additional mongod.exe options as required for your configuration.

5

Connect `mongo.exe` shell to `mongod.exe` and authenticate.¶

Connect the mongo.exe shell client as the Kerberos principal application@EXAMPLE.NET.

You can connect and authenticate from the command line.

mongo.exe --authenticationMechanism=GSSAPI --authenticationDatabase='$external' \
--username [email protected]

Or, alternatively, you can first connect mongo.exe to the mongod.exe, and then from the mongo.exe shell, use the db.auth() method to authenticate in the $external database.

use $external
db.auth( { mechanism: "GSSAPI", user: "[email protected]" } )

Additional Considerations¶

Configure `mongos.exe` for Kerberos¶

To start mongos.exe with Kerberos support, set the mongos.exe parameter authenticationMechanisms to GSSAPI. You must start mongos.exe as the service principal account.:

mongos.exe --setParameter authenticationMechanisms=GSSAPI <additional mongos options>

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

mongos.exe --setParameter authenticationMechanisms=GSSAPI --configdb shard0.example.net, shard1.example.net,shard2.example.net --keyFile C:\<path>\mongos.keyfile

Modify or include any additional mongos.exe options as required for your configuration. For example, instead of using --keyFile for internal authentication of sharded cluster members, you can use x.509 member authentication instead.

Assign Service Principal Name to MongoDB Windows Service¶

Use setspn.exe to assign the service principal name (SPN) to the account running the mongod.exe and the mongos.exe service:

setspn.exe -A <service>/<fully qualified domain name> <service account name>

For example, if mongod.exe runs as a service named mongodb on testserver.mongodb.com with the service account name mongodtest, assign the SPN as follows:

setspn.exe -A mongodb/testserver.mongodb.com mongodtest

Incorporate Additional Authentication Mechanisms¶

Kerberos authentication (GSSAPI (Kerberos)) can work alongside MongoDB’s challenge/response authentication mechanisms (SCRAM-SHA-1 and MONGODB-CR), MongoDB’s authentication mechanism for LDAP (PLAIN (LDAP SASL)), and MongoDB’s authentication mechanism for x.509 ( MONGODB-X509). Specify the mechanisms as follows:

--setParameter authenticationMechanisms=GSSAPI,SCRAM-SHA-1

Only add the other mechanisms if in use. This parameter setting does not affect MongoDB’s internal authentication of cluster members.

← Configure MongoDB with Kerberos Authentication on Linux Troubleshoot Kerberos Authentication →

Was this page helpful?

Yes No

Thank you for your feedback!

We're sorry! You can Report a Problem to help us improve this page.