- Security >
- Authentication >
- Enterprise Authentication Mechanisms >
- Kerberos Authentication >
- Configure MongoDB with Kerberos Authentication on Linux
Configure MongoDB with Kerberos Authentication on Linux¶
New in version 2.4.
Overview¶
MongoDB Enterprise supports authentication using a Kerberos service. Kerberos is an industry standard authentication protocol for large client/server system.
Prerequisites¶
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.
Procedure¶
The following procedure outlines the steps to add a Kerberos user
principal to MongoDB, configure a standalone mongod instance
for Kerberos support, and connect using the mongo shell and
authenticate the user principal.
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.
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.
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/[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.
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>
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
The path to your mongod as well as your keytab file may differ. Modify or include additional
mongod options as required for your configuration. 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 mongo shell to mongod and authenticate.¶
Connect the mongo shell 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.
mongo --host hostname.example.net --authenticationMechanism=GSSAPI --authenticationDatabase='$external' --username application/[email protected]
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, use --gssapiHostName
to specify the Kerberos FQDN that it responds to.
Alternatively, you can first connect mongo to the
mongod, and then from the mongo shell, use
the db.auth() method to authenticate in the
$external database.
use $external
db.auth( { mechanism: "GSSAPI", user: "application/[email protected]" } )
Additional Considerations¶
KRB5_KTNAME¶
If you installed MongoDB Enterprise using one of the official .deb
or .rpm packages, and you use the included init/upstart scripts to
control the mongod instance, you can set the KR5_KTNAME
variable in the default environment settings file instead of setting
the 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:
export KRB5_KTNAME="<path to keytab>"
Configure mongos for Kerberos¶
To start mongos with Kerberos support, set the environmental
variable KRB5_KTNAME to the path of its keytab file and the mongos parameter
authenticationMechanisms to GSSAPI in the following form:
env KRB5_KTNAME=<path to keytab file> \
mongos \
--setParameter authenticationMechanisms=GSSAPI \
<additional mongos options>
For example, the following starts a mongos instance with
Kerberos support:
env KRB5_KTNAME=/opt/mongodb/mongos.keytab \
mongos \
--setParameter authenticationMechanisms=GSSAPI \
--configdb shard0.example.net, shard1.example.net,shard2.example.net \
--keyFile /opt/mongodb/mongos.keyfile
The path to your mongos as well as your keytab file may differ. The keytab file must
be only accessible to the owner of the mongos process.
Modify or include any additional mongos 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.
Use a Config File¶
To configure mongod or mongos for Kerberos
support using a configuration file, specify the
authenticationMechanisms setting in the configuration file:
If using the YAML configuration file format:
setParameter:
authenticationMechanisms: GSSAPI
Or, if using the older .ini configuration file format:
setParameter=authenticationMechanisms=GSSAPI
Modify or include any additional mongod options as required
for your configuration. For example, if
/opt/mongodb/mongod.conf contains the following configuration
settings for a standalone mongod:
security:
authorization: enabled
setParameter:
authenticationMechanisms: GSSAPI
storage:
dbPath: /opt/mongodb/data
Or, if using the older configuration file format:
auth = true
setParameter=authenticationMechanisms=GSSAPI
dbpath=/opt/mongodb/data
To start mongod with Kerberos support, use the following
form:
env KRB5_KTNAME=/opt/mongodb/mongod.keytab \
/opt/mongodb/bin/mongod --config /opt/mongodb/mongod.conf
The path to your mongod, keytab file,
and configuration file may differ. The
keytab file must be only accessible to the owner
of the mongod process.
Troubleshoot Kerberos Setup for MongoDB¶
If you encounter problems when starting mongod or
mongos with Kerberos authentication, see
Troubleshoot Kerberos Authentication.
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.