Kerberos Authentication

Overview

MongoDB Enterprise provides support for Kerberos authentication ofMongoDB clients to mongod and mongos. Kerberos isan industry standard authentication protocol for large client/serversystems. Kerberos allows MongoDB and applications to take advantage ofexisting authentication infrastructure and processes.

Kerberos Components and MongoDB

Principals

In a Kerberos-based system, every participant in the authenticatedcommunication is known as a “principal”, and every principal must havea unique name.

Principals belong to administrative units called realms. For eachrealm, the Kerberos Key Distribution Center (KDC) maintains a databaseof the realm’s principal and the principals’ associated “secret keys”.

For a client-server authentication, the client requests from the KDC a“ticket” for access to a specific asset. KDC uses the client’ssecret and the server’s secret to construct the ticket which allows theclient and server to mutually authenticate each other, while keepingthe secrets hidden.

For the configuration of MongoDB for Kerberos support, two kinds ofprincipal names are of interest: user principals and service principals.

User Principal

To authenticate using Kerberos, you must add the Kerberos userprincipals to MongoDB to the $external database. User principalnames have the form:

  1. <username>@<KERBEROS REALM>

For every user you want to authenticate using Kerberos, you must createa corresponding user in MongoDB in the $external database.

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.

For examples of adding a user to MongoDB as well as authenticating asthat user, seeConfigure MongoDB with Kerberos Authentication on LinuxandConfigure MongoDB with Kerberos Authentication on Windows.

See also

Manage Users and Roles forgeneral information regarding creating and managing users inMongoDB.

Service Principal

Every MongoDB mongod and mongos instance (ormongod.exe or mongos.exe on Windows) must have anassociated service principal. Service principal names have the form:

  1. <service>/<fully qualified domain name>@<KERBEROS REALM>

For MongoDB, the <service> defaults to mongodb. For example, ifm1.example.com is a MongoDB server, and example.com maintainsthe EXAMPLE.COM Kerberos realm, then m1 should have the serviceprincipal name mongodb/m1.example.com@EXAMPLE.COM.

To specify a different value for <service>, useserviceName during the start up of mongod ormongos (or mongod.exe or mongos.exe).mongo shell or other clients may also specify a differentservice principal name using serviceName.

Service principal names must be reachable over the network using thefully qualified domain name (FQDN) part of its service principal name.

By default, Kerberos attempts to identify hosts using the/etc/krb5.conf file before using DNS to resolve hosts.

On Windows, if running MongoDB as a service, seeAssign Service Principal Name to MongoDB Windows Service.

Linux Keytab Files

Linux systems can store Kerberos authentication keys for aservice principal in _keytab_files. Each Kerberized mongod and mongos instancerunning on Linux must have access to a keytab file containing keys forits service principal.

To keep keytab files secure, use file permissions that restrict accessto only the user that runs the mongod or mongosprocess.

Tickets

On Linux, MongoDB clients can use Kerberos’s kinit program toinitialize a credential cache for authenticating the user principal toservers.

Windows Active Directory

Unlike on Linux systems, mongod and mongosinstances running on Windows do not require access to keytab files.Instead, the mongod and mongos instances readtheir server credentials from a credential store specific to theoperating system.

However, from the Windows Active Directory, you can export a keytabfile for use on Linux systems. See Ktpass for moreinformation.

Authenticate With Kerberos

To configure MongoDB for Kerberos support and authenticate, seeConfigure MongoDB with Kerberos Authentication on LinuxandConfigure MongoDB with Kerberos Authentication on Windows.

Operational Considerations

The HTTP Console

The MongoDB HTTP Console interface does not supportKerberos authentication.

Changed in version 3.6: MongoDB 3.6 removes the deprecated HTTP interface and REST API toMongoDB.

DNS

Each host that runs a mongod or mongos instancemust have both A and PTR DNS records to provide forward andreverse lookup.

Without A and PTR DNS records, the host cannot resolve thecomponents of the Kerberos domain or the Key Distribution Center (KDC).

System Time Synchronization

To successfully authenticate, the system time for eachmongod and mongos instance must be within5 minutes of the system time of the other hosts in the Kerberosinfrastructure.

Kerberized MongoDB Environments

Driver Support

The following MongoDB drivers support Kerberos authentication:

Use with Additional MongoDB Authentication Mechanism

Although MongoDB supports the use of Kerberos authentication with otherauthentication mechanisms, only add the other mechanisms as necessary.See the Incorporate Additional Authentication Mechanisms section inConfigure MongoDB with Kerberos Authentication on LinuxandConfigure MongoDB with Kerberos Authentication on Windowsfor details.