Troubleshoot Kerberos Authentication
On this page
mongokerberos
Validation Tool
Introduced alongside MongoDB 4.4, the mongokerberos
program provides a convenient method to verify your platform's Kerberos
configuration for use with MongoDB, and to test that Kerberos
authentication from a MongoDB client works as expected.
The mongokerberos
tool can help diagnose common
configuration issues, and is the recommended place to start when
troubleshooting your Kerberos configuration. See the
mongokerberos
documentation for more information.
mongokerberos
is available in MongoDB Enterprise only.
Kerberos Configuration Debugging Strategies
If you have difficulty starting or authenticating against
mongod
or mongos
with Kerberos:
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.
To verify that you are using MongoDB Enterprise, pass the
--version
command line option to themongod
ormongos
:mongod --version In the output from this command, look for the string
modules: subscription
ormodules: enterprise
to confirm you are using the MongoDB Enterprise binaries.Ensure that the canonical system hostname of the
mongod
ormongos
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 SPN is notmongodb
, you must specify the primary component using--setParameter saslServiceName
.
On Linux, ensure that the instance component of the service principal name (SPN) in the keytab file matches the canonical system hostname of the
mongod
ormongos
instance. If themongod
ormongos
instance's system hostname is not in the keytab file, authentication will fail with aGSSAPI error acquiring credentials.
error message.If the hostname of your
mongod
ormongos
instance as returned byhostname -f
is not fully qualified, use--setParameter saslHostName
to set the instance's fully qualified domain name when starting yourmongod
ormongos
.Ensure that each host that runs a
mongod
ormongos
instance hasA
andPTR
DNS records to provide both forward and reverse DNS lookup. TheA
record should map to themongod
ormongos
's FQDN.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
mongod
, mongos
, or mongo
instances to
produce verbose logging.
For example, the following command starts a standalone mongod
whose keytab file is at the default /etc/krb5.keytab
path
and 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 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.