Configure MongoDB with Kerberos Authentication on Linux

Overview

MongoDB Enterprise supports authentication using a Kerberosservice. Kerberos is an industry standardauthentication protocol for large client/server system.

Prerequisites

Setting up and configuring a Kerberos deployment is beyond the scope ofthis document. This tutorial assumes you have configured aKerberos service principal for eachmongod and mongos instance in your MongoDBdeployment, and you have a valid keytab file forfor each mongod and mongos instance.

For replica sets and sharded clusters, ensure that your configurationuses fully qualified domain names (FQDN) rather than IP addresses orunqualified hostnames. You must use the FQDN for GSSAPI to correctlyresolve the Kerberos realms and allow you to connect.

To verify MongoDB Enterprise binaries, pass the —version command lineoption to the mongod or mongos:

  1. mongod --version

In the output from this command, look for the string modules:subscription or modules: enterprise to confirm your system hasMongoDB Enterprise.

Procedure

The following procedure outlines the steps to add a Kerberos userprincipal to MongoDB, configure a standalone mongod instancefor Kerberos support, and connect using the mongo shell andauthenticate the user principal.

Start mongod without Kerberos.

For the initial addition of Kerberos users, start mongodwithout Kerberos support.

If a Kerberos user is already in MongoDB and has theprivileges required to create a user, you can startmongod with Kerberos support.

Include additional settings as appropriate to your deployment.

Note

Starting in MongoDB 3.6, mongod and mongosbind to localhost by default. If the members of your deployment arerun on different hosts or if you wish remote clients to connect toyour deployment, you must specify —bind_ip ornet.bindIp. For more information, seeLocalhost Binding Compatibility Changes.

Connect to mongod.

Connect via the mongo shell to the mongodinstance. If mongod has —auth enabled, ensureyou 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 anexternal source (e.g. Kerberos) to authenticate. To specify theuser’s privileges, assign roles to theuser.

Changed in version 3.6.3: To use sessions with $external authentication users (i.e.Kerberos, LDAP, x.509 users), the usernames cannot be greaterthan 10k bytes.

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

  1. use $external
  2. db.createUser(
  3.    {
  4.      user: "application/reporting@EXAMPLE.NET",
  5.      roles: [ { role: "read", db: "records" } ]
  6.    }
  7. )

Add additional principals as needed. For every user you want toauthenticate using Kerberos, you must create a corresponding user inMongoDB.For moreinformation about creating and managing users, seeUser Management Commands.

Start mongod with Kerberos support.

To start mongod with Kerberos support, set theenvironmental variable KRB5_KTNAME to the path of the keytabfile and the mongod parameterauthenticationMechanisms to GSSAPI in thefollowing form:

  1. env KRB5_KTNAME=<path to keytab file> \
  2. mongod \
  3. --setParameter authenticationMechanisms=GSSAPI \
  4. <additional mongod options>

Include additional options as required for your configuration. Forinstance, if you wish remote clients to connect to your deploymentor your deployment members are run on different hosts, specify the—bind_ip. For more information, seeLocalhost Binding Compatibility Changes.

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

  1. env KRB5_KTNAME=/opt/mongodb/mongod.keytab \
  2. /opt/mongodb/bin/mongod --auth \
  3. --setParameter authenticationMechanisms=GSSAPI \
  4. --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 filemust be only accessible to the owner of the mongodprocess.

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

Connect mongo shell to mongod and authenticate.

Connect the mongo shell client as the Kerberos principalapplication/reporting@EXAMPLE.NET. Before connecting, youmust have used Kerberos’s kinit program to get credentials forapplication/reporting@EXAMPLE.NET.

You can connect and authenticate from the command line.

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

If you are connecting to a system whose hostname matches theKerberos name, ensure that you specify the fully qualifieddomain name (FQDN) for the —hostoption, rather than an IP address or unqualified hostname.

If you are connecting to a system whose hostname does notmatch the Kerberos name, use —gssapiHostNameto specify the Kerberos FQDN that it responds to.

Alternatively, you can first connect mongo to themongod, and then from the mongo shell, usethe db.auth() method to authenticate in the$external database.

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

Additional Considerations

KRB5_KTNAME

If you installed MongoDB Enterprise using one of the official .debor .rpm packages, and you use the included init/upstart scripts tocontrol the mongod instance, you can set the KR5_KTNAMEvariable in the default environment settings file instead of settingthe variable each time.

For .rpm packages, the default environment settings file is/etc/sysconfig/mongod.

For .deb packages, the file is /etc/default/mongodb.

Set the KRB5_KTNAME value in a line that resembles the following:

  1. export KRB5_KTNAME="<path to keytab>"

Configure mongos for Kerberos

To start mongos with Kerberos support, set the environmentalvariable KRB5_KTNAME to the path of its keytab file and the mongos parameterauthenticationMechanisms to GSSAPI in the following form:

  1. env KRB5_KTNAME=<path to keytab file> \
  2. mongos \
  3. --setParameter authenticationMechanisms=GSSAPI \
  4. <additional mongos options>

Include additional options as required for your configuration. Forinstance, if you wish remote clients to connect to your deploymentor your deployment members are run on different hosts, specify the—bind_ip. For more information, seeLocalhost Binding Compatibility Changes.

For example, the following starts a mongos instance withKerberos support:

  1. env KRB5_KTNAME=/opt/mongodb/mongos.keytab \
  2. mongos \
  3. --setParameter authenticationMechanisms=GSSAPI \
  4. --configdb shard0.example.net, shard1.example.net,shard2.example.net \
  5. --keyFile /opt/mongodb/mongos.keyfile \
  6. --bind_ip localhost,<hostname(s)|ip address(es)>

The path to your mongos as well as your keytab file may differ. The keytab file mustbe only accessible to the owner of the mongos process.

Modify or include any additional mongos options as requiredfor your configuration. For example, instead of using—keyFile for internal authentication of sharded clustermembers, you can use x.509 member authentication instead.

Use a Config File

To configure mongod or mongos for Kerberossupport using a configuration file, specify theauthenticationMechanisms setting in the configuration file.

If using the YAML configuration file format:

  1. setParameter:
  2.    authenticationMechanisms: GSSAPI

Include additional options as requiredfor your configuration. For instance, if you wish remote clients toconnect to your deployment or your deployment members are run ondifferent hosts, specify the net.bindIp setting. For moreinformation, see Localhost Binding Compatibility Changes.

For example, if /opt/mongodb/mongod.conf contains the followingconfiguration settings for a standalone mongod:

  1. security:
  2.    authorization: enabled
  3. setParameter:
  4.    authenticationMechanisms: GSSAPI
  5. storage:
  6.    dbPath: /opt/mongodb/data
  7. net:
  8.    bindIp: localhost,<hostname(s)|ip address(es)>

To start mongod with Kerberos support, use the followingform:

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

The path to your mongod, keytab file,and configuration file may differ. Thekeytab file must be only accessible to the ownerof the mongod process.

Troubleshoot Kerberos Setup for MongoDB

If you encounter problems when starting mongod ormongos with Kerberos authentication, seeTroubleshoot Kerberos Authentication.

Incorporate Additional Authentication Mechanisms

Kerberos authentication (GSSAPI (Kerberos))can work alongside:

  • MongoDB’s SCRAM authentication mechanism:
  • MongoDB’s authentication mechanism for LDAP:
  • MongoDB’s authentication mechanism for x.509:

Specify the mechanisms as follows:

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

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