Troubleshoot Kerberos Authentication

Troubleshoot Kerberos Authentication

Kerberos Configuration Debugging Strategies

If you have difficulty starting or authenticating againstmongod or mongos with Kerberos:

Ensure that you are running MongoDB Enterprise, not MongoDB CommunityEdition. Kerberos authentication is a MongoDB Enterprise featureand will not work with MongoDB Community Edition binaries.

To verify MongoDB Enterprise binaries, pass the —version command lineoption to the mongod or mongos:

mongod --version

In the output from this command, look for the string modules:subscription or modules: enterprise to confirm your system hasMongoDB Enterprise.

Ensure that the canonical system hostname of themongod or mongos instance is a resolvable,fully qualified domain name.

On Linux, you can verify the system hostname resolution with the hostname-f command 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 SPNis not mongodb,you must specify the primary component using—setParameter saslServiceName.

On Linux, ensure that the instance component of the service principalname (SPN)in thekeytab file matches the canonical system hostnameof the mongod or mongosinstance. If the mongod or mongosinstance’s system hostname is not in the keytab file,authentication will fail with a GSSAPI error acquiringcredentials. error message.

If the hostname of your mongod or mongos instanceas returned by hostname -fis not fully qualified,use —setParameter saslHostName to set the instance’s fully qualified domain name whenstarting your mongod or mongos.

Ensure that each host that runs a mongod ormongos instance has A and PTR DNS records toprovide both forward and reverse DNS lookup. The A record shouldmap to the mongod or mongos’s FQDN.
Ensure that clocks on the servers hosting your MongoDB instances andKerberos infrastructure are within the maximum time skew: 5 minutesby default. Time differences greater than the maximum time skewprevent successful authentication.

Kerberos Trace Logging on Linux

MIT Kerberos provides the KRB5_TRACE environment variable fortrace logging output. If you are having persistent problems withMIT Kerberos on Linux, you can set KRB5_TRACE when starting yourmongod, mongos, or mongo instances toproduce verbose logging.

For example, the following command starts a standalone mongodwhose keytab file is at the default /etc/krb5.keytab pathand sets KRB5_TRACE to write to /logs/mongodb-kerberos.log:

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 \
    --bind_ip localhost,<hostname(s)|ip address(es)> --fork

Common Error Messages

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

GSSAPI error in client while negotiating security context.
This error occurs on the client and reflects insufficient credentialsor a malicious attempt to authenticate.

If you receive this error, ensure that you are using the correctcredentials and the correct fully qualified domain name whenconnecting to the host.

GSSAPI error acquiring credentials.
This error occurs during the start of the mongod ormongos and reflects improper configuration of the systemhostname or a missing or incorrectly configured keytab file.