Configure MongoDB with Kerberos Authentication on Linux
Overview
MongoDB Enterprise supports authentication using a Kerberos service. Kerberos is an industry standard authentication protocol for large client/server systems. MongoDB Enterprise only supports the MIT implementation of Kerberos.
Prerequisites
To verify that you are using MongoDB Enterprise, 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 you are using the
MongoDB Enterprise binaries.
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.
Setting up and configuring a Kerberos deployment is beyond the scope of this document. Please refer to the MIT Kerberos documentation or your operating system documentation for information on how to configure a Kerberos deployment.
In order to use MongoDB with Kerberos, a
Kerberos service principal for each
mongod
and mongos
instance in your MongoDB
deployment must be added to the Kerberos database.
You can add the service principal by running a command similar to the
following on your KDC:
kadmin.local addprinc mongodb/m1.example.com@EXAMPLE.COM
On each system running mongod
or mongos
,
a keytab file must be created
for the respective service principal. You can create the keytab file by
running a command similar to the following on the system running
mongod
or mongos
:
kadmin.local ktadd mongodb/m1.example.com@EXAMPLE.COM
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.
Include additional settings as appropriate to your deployment.
Note
mongod
and mongos
bind to localhost by default. If the members of your deployment are
run on different hosts or if you wish remote clients to connect to
your deployment, you must specify --bind_ip
or
net.bindIp
.
Connect to mongod
.
Connect via the mongo
shell 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.
Changed in version 3.6.3: To use sessions with $external
authentication users (i.e.
Kerberos, LDAP, 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 more information, see
Localhost Binding Compatibility Changes.
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 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/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, 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/reporting@EXAMPLE.NET" } )
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 KRB5_KTNAME
variable in the default environment settings file instead of setting
the variable each time.
Recent versions of Red Hat and Debian-based systems use systemd
.
Older versions use init
for system initialization. Follow the
appropriate instructions to configure the KRB5_KTNAME
variable for
your system.
systemd
Configuration Files
systemd
stores configuration in unit files. Update the unit file to
set the KRB5_KTNAME
variable.
Edit the unit file
Add the edited line to the unit file. The edited unit file will resemble:
[Unit] Description=High-performance, schema-free document-oriented database After=network.target Documentation=https://docs.mongodb.org/manual [Service] User=mongodb Group=mongodb ExecStart=/usr/bin/mongod --config /etc/mongod.conf Environment="KRB5_KTNAME=/etc/mongod.keytab" PIDFile=/var/run/mongodb/mongod.pid file size LimitFSIZE=infinity cpu time LimitCPU=infinity virtual memory size LimitAS=infinity open files LimitNOFILE=64000 processes/threads LimitNPROC=64000 locked memory LimitMEMLOCK=infinity total threads (user+kernel) TasksMax=infinity TasksAccounting=false Recommended limits for for mongod as specified in http://docs.mongodb.org/manual/reference/ulimit/#recommended-settings [Install] WantedBy=multi-user.target
Restart the mongod
service
sudo systemctl restart mongod
init
Configuration Files
For .rpm
installations, the default environment settings file is
/etc/sysconfig/mongod
.
For .deb
installations, the file is /etc/default/mongodb
.
Set the KRB5_KTNAME
value by adding a line that resembles the
following:
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>
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 more information, see
Localhost Binding Compatibility Changes.
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 \ --bind_ip localhost,<hostname(s)|ip address(es)>
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
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 net.bindIp
setting. For more
information, see Localhost Binding Compatibility Changes.
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 net: bindIp: localhost,<hostname(s)|ip address(es)>
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 SCRAM authentication mechanism:
SCRAM-SHA-256 (Added in MongoDB 4.0)
MongoDB's authentication mechanism for LDAP:
PLAIN (LDAP SASL)
MongoDB's authentication mechanism for x.509:
Specify the mechanisms as follows:
--setParameter authenticationMechanisms=GSSAPI,SCRAM-SHA-256
Only add the other mechanisms if in use. This parameter setting does not affect MongoDB's internal authentication of cluster members.
Testing and Verification
After completing the configuration steps, you can validate your
configuration with the mongokerberos
tool.
Introduced alongside MongoDB 4.4, mongokerberos
provides a convenient method to verify your platform's Kerberos
configuration for use with MongoDB, and to test that Kerberos
authentication from a MongoDB client works as expected. See the
mongokerberos
documentation for more information.
mongokerberos
is available in MongoDB Enterprise only.