- Security >
- Security Tutorials >
- Access Control Tutorials >
- Deploy MongoDB with Kerberos Authentication
Deploy MongoDB with Kerberos Authentication¶
On this page
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
andmongos
instance in your MongoDB deployment. - Generate and distribute keytab files for each MongoDB component
(i.e.
mongod
andmongos
)in your deployment. Ensure that you only transmit keytab files over secure channels. - Optional. Start the
mongod
instance withoutauth
and create users inside of MongoDB that you can use to bootstrap your deployment. - Start
mongod
andmongos
with theKRB5_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:
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:
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:
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:
For successful operation with mongod
use the following run
time options in addition to your normal default configuration options:
--setParameter
with theauthenticationMechanisms=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
impliesauth
.
For example, consider the following invocation:
You can also specify these options using the configuration file. As in the following:
To use this configuration file, start mongod
as in the
following:
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:
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:
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:
Alternately, you can authenticate using command line options to
mongo
, as in the following equivalent example:
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 themongod
instance running on thedb0.example.net
host, the service principal should bemongodb/db0.example.net
. - DNS allows the
mongod
to resolve the components of the Kerberos infrastructure. You should have bothA
andPTR
records (i.e. forward and reverse DNS) for the system that runs themongod
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 thehostname -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:
[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
ormongos
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:
Replace
<keytab>
with the path to your keytab file.check the configured hostname for your system, with the following command:
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:
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.