- Security >
- Security Tutorials >
- Access Control Tutorials >
- Troubleshoot Kerberos Authentication on Linux
Troubleshoot Kerberos Authentication on Linux¶
New in version 2.4.
Kerberos Configuration Checklist¶
If you have difficulty starting mongod
or mongos
with Kerberos on Linux systems, ensure that:
The
mongod
and themongos
binaries are from MongoDB Enterprise.To verify MongoDB Enterprise binaries:
In the output from this command, look for the string
modules: subscription
ormodules: 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.
Either the service principal name (SPN) in the keytab file matches the SPN for the
mongod
ormongos
instance, or themongod
or themongos
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
ormongos
instance is a resolvable, fully qualified domain for this host. You can test the system hostname resolution with thehostname -f
command at the system prompt.Each host that runs a
mongod
ormongos
instance has both theA
andPTR
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 ormongos
must be able to resolve each other using DNS. By default, Kerberos attempts to resolve hosts using the content of the/etc/krb5.conf
before using DNS to resolve hosts.The time synchronization of the systems running
mongod
or themongos
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¶
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:
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
ormongos
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
ormongos
instance.To determine whether the SPNs match:
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 start
mongod
ormongos
with the--setParameter saslHostName=<hostname>
.