Navigation
This version of the documentation is archived and no longer supported.

Deploy MongoDB with Kerberos Authentication

New in version 2.4.

MongoDB Enterprise supports authentication using a Kerberos service. Kerberos is an industry standard authentication protocol for large client/server system. With Kerberos MongoDB and application ecosystems can take advantage of existing authentication infrastructure and processes.

Setting up and configuring a Kerberos deployment is beyond the scope of this document. In order to use MongoDB with Kerberos, you must have a properly configured Kerberos deployment and the ability to generate a valid keytab file for each mongod instance in your MongoDB deployment.

Note

The following assumes that you have a valid Kerberos keytab file for your realm accessible on your system. The examples below assume that the keytab file is valid and is located at /opt/mongodb/mongod.keytab and is only accessible to the user that runs the mongod process.

Process Overview

To run MongoDB with Kerberos support, you must:

  • Configure a Kerberos service principal for each mongod and mongos instance in your MongoDB deployment.
  • Generate and distribute keytab files for each MongoDB component (i.e. mongod and mongos)in your deployment. Ensure that you only transmit keytab files over secure channels.
  • Optional. Start the mongod instance without auth and create users inside of MongoDB that you can use to bootstrap your deployment.
  • Start mongod and mongos with the KRB5_KTNAME environment variable as well as a number of required run time options.
  • If you did not create Kerberos user accounts, you can use the localhost exception to create users at this point until you create the first user on the admin database.
  • Authenticate clients, including the mongo shell using Kerberos.

Operations

Create Users and Privilege Documents

For every user that you want to be able to authenticate using Kerberos, you must create corresponding privilege documents in the system.users collection to provision access to users. Consider the following document:

{
  user: "application/reporting@EXAMPLE.NET",
  roles: ["read"],
  userSource: "$external"
}

This grants the Kerberos user principal application/reporting@EXAMPLE.NET read only access to a database. The userSource $external reference allows mongod to consult an external source (i.e. Kerberos) to authenticate this user.

In the mongo shell you can pass the db.addUser() a user privilege document to provision access to users, as in the following operation:

db = db.getSiblingDB("records")
db.addUser( {
              "user": "application/reporting@EXAMPLE.NET",
              "roles": [ "read" ],
              "userSource": "$external"
            } )

These operations grants the Kerberos user application/reporting@EXAMPLE.NET access to the records database.

To remove access to a user, use the remove() method, as in the following example:

db.system.users.remove( { user: "application/reporting@EXAMPLE.NET" } )

To modify a user document, use update operations on documents in the system.users collection.

Start mongod with Kerberos Support

Once you have provisioned privileges to users in the mongod, and obtained a valid keytab file, you must start mongod using a command in the following form:

env KRB5_KTNAME=<path to keytab file> <mongod invocation>

For successful operation with mongod use the following run time options in addition to your normal default configuration options:

  • --setParameter with the authenticationMechanisms=GSSAPI argument to enable support for Kerberos.
  • --auth to enable authentication.
  • --keyFile to allow components of a single MongoDB deployment to communicate with each other, if needed to support replica set and sharded cluster operations. keyFile implies auth.

For example, consider the following invocation:

env KRB5_KTNAME=/opt/mongodb/mongod.keytab \
    /opt/mongodb/bin/mongod --dbpath /opt/mongodb/data \
    --fork --logpath /opt/mongodb/log/mongod.log \
    --auth --setParameter authenticationMechanisms=GSSAPI

You can also specify these options using the configuration file. As in the following:

# /opt/mongodb/mongod.conf, Example configuration file.

fork = true
auth = true

dbpath = /opt/mongodb/data
logpath = /opt/mongodb/log/mongod.log
setParameter = authenticationMechanisms=GSSAPI

To use this configuration file, start mongod as in the following:

env KRB5_KTNAME=/opt/mongodb/mongod.keytab \
    /opt/mongodb/bin/mongod --config /opt/mongodb/mongod.conf

To start a mongos instance using Kerberos, you must create a Kerberos service principal and deploy a keytab file for this instance, and then start the mongos with the following invocation:

env KRB5_KTNAME=/opt/mongodb/mongos.keytab \
    /opt/mongodb/bin/mongos
    --configdb shard0.example.net,shard1.example.net,shard2.example.net \
    --setParameter authenticationMechanisms=GSSAPI \
    --keyFile /opt/mongodb/mongos.keyfile

Tip

If you installed MongoDB Enterprise using one of the official .deb or .rpm packages and are controlling the mongod instance using the included init/upstart scripts, you can set the KR5_KTNAME variable in the default environment settings file. For .rpm packages this file is located at /etc/sysconfig/mongod. For .deb packages, this file is /etc/default/mongodb. Set the value in a line that resembles the following:

export KRB5_KTNAME="<setting>"

If you encounter problems when trying to start mongod or mongos, please see the troubleshooting section for more information.

Important

Before users can authenticate to MongoDB using Kerberos you must create users and grant them privileges within MongoDB. If you have not created users when you start MongoDB with Kerberos you can use the localhost authentication exception to add users. See the Create Users and Privilege Documents section and the User Privilege Roles in MongoDB document for more information.

Authenticate mongo Shell with Kerberos

To connect to a mongod instance using the mongo shell you must begin by using the kinit program to initialize and authenticate a Kerberos session. Then, start a mongo instance, and use the db.auth() method, to authenticate against the special $external database, as in the following operation:

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

Alternately, you can authenticate using command line options to mongo, as in the following equivalent example:

mongo --authenticationMechanism=GSSAPI
      --authenticationDatabase='$external' \
      --username application/reporting@EXAMPLE.NET

These operations authenticate the Kerberos principal name application/reporting@EXAMPLE.NET to the connected mongod, and will automatically acquire all available privileges as needed.

Use MongoDB Drivers to Authenticate with Kerberos

At the time of release, the C++, Java, C#, and Python drivers all provide support for Kerberos authentication to MongoDB. Consider the following tutorials for more information:

Kerberos and the HTTP Console

MongoDB does not support kerberizing the HTTP Console.

Troubleshooting

Kerberos Configuration Checklist

If you’re having trouble getting mongod to start with Kerberos, there are a number of Kerberos-specific issues that can prevent successful authentication. As you begin troubleshooting your Kerberos deployment, ensure that:

  • The mongod is from MongoDB Enterprise.
  • You are not using the HTTP Console. MongoDB Enterprise does not support Kerberos authentication over the HTTP Console interface.
  • You have a valid keytab file specified in the environment running the mongod. For the mongod instance running on the db0.example.net host, the service principal should be mongodb/db0.example.net.
  • DNS allows the mongod to resolve the components of the Kerberos infrastructure. You should have both A and PTR records (i.e. forward and reverse DNS) for the system that runs the mongod instance.
  • The canonical system hostname of the system that runs the mongod instance is the resolvable fully qualified domain for this host. Test system hostname resolution with the hostname -f command at the system prompt.
  • Both the Kerberos KDC and the system running mongod instance must be able to resolve each other using DNS [1]
  • The time systems of the systems running the mongod instances and the Kerberos infrastructure are synchronized. Time differences greater than 5 minutes will prevent successful authentication.

If you still encounter problems with Kerberos, you can start both mongod and mongo (or another client) with the environment variable KRB5_TRACE set to different files to produce more verbose logging of the Kerberos process to help further troubleshooting, as in the following example:

env KRB5_KTNAME=/opt/mongodb/mongod.keytab \
    KRB5_TRACE=/opt/mongodb/log/mongodb-kerberos.log \
    /opt/mongodb/bin/mongod --dbpath /opt/mongodb/data \
    --fork --logpath /opt/mongodb/log/mongod.log \
    --auth --setParameter authenticationMechanisms=GSSAPI
[1]By default, Kerberos attempts to resolve hosts using the content of the /etc/krb5.conf before using DNS to resolve hosts.

Common Error Messages

In some situations, MongoDB will return error messages from the GSSAPI interface if there is a problem with the Kerberos service.

GSSAPI error in client while negotiating security context.

This error occurs on the client and reflects insufficient credentials or a malicious attempt to authenticate.

If you receive this error ensure that you’re using the correct credentials and the correct fully qualified domain name when connecting to the host.

GSSAPI error acquiring credentials.

This error only occurs when attempting to start the mongod or mongos and reflects improper configuration of system hostname or a missing or incorrectly configured keytab file. If you encounter this problem, consider all the items in the Kerberos Configuration Checklist, in particular:

  • examine the keytab file, with the following command:

    klist -k <keytab>
    

    Replace <keytab> with the path to your keytab file.

  • check the configured hostname for your system, with the following command:

    hostname -f
    

    Ensure that this name matches the name in the keytab file, or use the saslHostName to pass MongoDB the correct hostname.

Enable the Traditional MongoDB Authentication Mechanism

For testing and development purposes you can enable both the Kerberos (i.e. GSSAPI) authentication mechanism in combination with the traditional MongoDB challenge/response authentication mechanism (i.e. MONGODB-CR), using the following setParameter run-time option:

mongod --setParameter authenticationMechanisms=GSSAPI,MONGODB-CR

Warning

All keyFile internal authentication between members of a replica set or sharded cluster still uses the MONGODB-CR authentication mechanism, even if MONGODB-CR is not enabled. All client authentication will still use Kerberos.