Troubleshoot Kerberos Authentication¶

On this page

Kerberos Configuration Checklist
Debug with More Verbose Logs on Linux
Common Error Messages

New in version 2.4.

Kerberos Configuration Checklist¶

If you have difficulty starting mongod or mongos with Kerberos, ensure that:

The mongod and the mongos binaries are from MongoDB Enterprise.

To verify MongoDB Enterprise binaries:
```
mongod --version
```
In the output from this command, look for the string modules: subscription or modules: enterprise to confirm your system has MongoDB Enterprise.
You are not using the HTTP Console. MongoDB Enterprise does not support Kerberos authentication over the HTTP Console interface.
On Linux, either the service principal name (SPN) in the keytab file matches the SPN for the mongod or mongos instance, or the mongod or the mongos instance use the --setParameter saslHostName=<host name> to match the name in the keytab file.
The canonical system hostname of the system that runs the mongod or mongos instance is a resolvable, fully qualified domain for this host. You can test the system hostname resolution with the hostname -f command at the system prompt.
Each host that runs a mongod or mongos instance has both the A and PTR DNS records to provide forward and reverse lookup. The records allow the host to resolve the components of the Kerberos infrastructure.
Both the Kerberos Key Distribution Center (KDC) and the system running mongod instance or mongos must be able to resolve each other using DNS. By default, Kerberos attempts to resolve hosts using the content of the /etc/kerb5.conf before using DNS to resolve hosts.
The time synchronization of the systems running mongod or the mongos instances and the Kerberos infrastructure are within the maximum time skew (default is 5 minutes) of each other. Time differences greater than the maximum time skew will prevent successful authentication.

Debug with More Verbose Logs on Linux¶

If you still encounter problems with Kerberos on Linux, 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. For example, the following starts a standalone mongod with KRB5_TRACE set:

env KRB5_KTNAME=/opt/mongodb/mongod.keytab \
    KRB5_TRACE=/opt/mongodb/log/mongodb-kerberos.log \
    /opt/mongodb/bin/mongod --dbpath /opt/mongodb/data \
    --fork --logpath /opt/mongodb/log/mongod.log \
    --auth --setParameter authenticationMechanisms=GSSAPI

Common Error Messages¶

In some situations, MongoDB will return error messages from the GSSAPI interface if there is a problem with the Kerberos service. Some common error messages are:

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 are using the correct credentials and the correct fully qualified domain name when connecting to the host.

GSSAPI error acquiring credentials.

This error occurs during the start of the mongod or mongos and reflects improper configuration of the system hostname or a missing or incorrectly configured keytab file.

If you encounter this problem, consider the items in the Kerberos Configuration Checklist, in particular, whether the SPN in the keytab file matches the SPN for the mongod or mongos instance.

To determine whether the SPNs match:

Examine the keytab file, with the following command:
```
klist -k <keytab>
```
Replace <keytab> with the path to your keytab file.
Check the configured hostname for your system, with the following command:
```
hostname -f
```
Ensure that this name matches the name in the keytab file, or start mongod or mongos with the --setParameter saslHostName=<hostname>.