Troubleshoot Kerberos Authentication¶
On this page
New in version 2.4.
Kerberos Configuration Debugging Strategies¶
Ensure that you are running MongoDB Enterprise, not MongoDB Community Edition. Kerberos authentication is a MongoDB Enterprise feature and will not work with MongoDB Community Edition binaries.
In the output from this command, look for the string
modules: enterpriseto confirm your system has MongoDB Enterprise.
On Linux, you can verify the system hostname resolution with the
hostname -fcommand at the system prompt.
On Linux, ensure that the primary component of the service principal name (SPN) of the SPN is
mongodb. If the primary component of the SPN is not
mongodb, you must specify the primary component using
On Linux, ensure that the instance component of the service principal name (SPN) in the keytab file matches the canonical system hostname of the
mongosinstance. If the
mongosinstance’s system hostname is not in the keytab file, authentication will fail with a
GSSAPI error acquiring credentials.error message.
If the hostname of your
mongosinstance as returned by
hostname -fis not fully qualified, use
--setParameter saslHostNameto set the instance’s fully qualified domain name when starting your
Ensure that clocks on the servers hosting your MongoDB instances and Kerberos infrastructure are within the maximum time skew: 5 minutes by default. Time differences greater than the maximum time skew prevent successful authentication.
Kerberos Trace Logging on Linux¶
MIT Kerberos provides the
KRB5_TRACE environment variable for
trace logging output. If you are having persistent problems with
MIT Kerberos on Linux, you can set
KRB5_TRACE when starting your
mongo instances to
produce verbose logging.
For example, the following command starts a standalone
whose keytab file is at the default
KRB5_TRACE to write to
env KRB5_KTNAME=/etc/krb5.keytab \ KRB5_TRACE=/logs/mongodb-kerberos.log \ mongod --dbpath /data/db --logpath /data/db/mongodb.log \ --auth --setParameter authenticationMechanisms=GSSAPI --fork
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
mongosand reflects improper configuration of the system hostname or a missing or incorrectly configured keytab file.