Kerberos (GSSAPI)

On this page

Overview
Code Placeholders
Specify GSSAPI Authentication
Additional Properties
Configure Caching Behavior
API Documentation

Overview

The Generic Security Services API (GSSAPI) authentication mechanism allows you to use your principal name to authenticate to a Kerberos service. You can use this mechanism only when authenticating to MongoDB Enterprise Advanced.

Code Placeholders

The code examples on this page use the following placeholders:

<db_username>: Your URL-encoded principal name. For example: "username%40REALM.ME"
<hostname>: The network address of your MongoDB deployment.
<port>: The port number of your MongoDB deployment. If you omit this parameter, the driver uses the default port number (27017).

To use the code examples, replace these placeholders with your own values.

Specify GSSAPI Authentication

Select the Connection String or the MongoCredential tab below for instructions and sample code for specifying this authentication mechanism:

To specify the GSSAPI authentication mechanism by using a connection string, perform the following actions:

Assign the authMechanism URL parameter to the value GSSAPI
(optional) Assign the authSource URL parameter to the value $external

Note

If you specify the GSSAPI mechanism, you cannot assign authSource to any value other than $external.

The code to instantiate a MongoClient resembles the following:

MongoClient mongoClient = MongoClients.create("<db_username>@<hostname>:<port>/?authSource=$external&authMechanism=GSSAPI");

To specify the GSSAPI authentication mechanism by using the MongoCredential class, use the createGSSAPICredential() method. The code to instantiate a MongoClient resembles the following:

MongoCredential credential = MongoCredential.createGSSAPICredential(<db_username>);
MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
                builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
        .credential(credential)
        .build());

To acquire a Kerberos ticket, the GSSAPI Java libraries require you to specify the realm and Key Distribution Center (KDC) system properties. See the sample settings in the following example:

java.security.krb5.realm=MYREALM.ME
java.security.krb5.kdc=mykdc.myrealm.me

Additional Properties

You might need to specify one or more of the following MongoCredential mechanism properties depending on your Kerberos setup:

SERVICE_NAME
CANONICALIZE_HOST_NAME
JAVA_SUBJECT
JAVA_SASL_CLIENT_PROPERTIES
JAVA_SUBJECT_PROVIDER

Important

You can only specify the following GSSAPI properties using the MongoCredential:

JAVA_SUBJECT
JAVA_SASL_CLIENT_PROPERTIES
JAVA_SUBJECT_PROVIDER

Select the MongoCredential tab to see how to specify them.

To specify one of the GSSAPI additional properties, include it in the connection string as a URL parameter using the format: <PROPERTY_NAME>:<value>.

Your code to instantiate a MongoClient using GSSAPI and additional properties might resemble the following:

MongoClient mongoClient = MongoClients.create("<db_username>@<hostname>:<port>/?authSource=$external&authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:myService");

To specify one of the GSSAPI additional properties, call the withMechanismProperty() method on your MongoCredential instance and pass the property name and value as parameters. Use the property name constants defined in the MongoCredential class:

Select the SERVICE_NAME_KEY or JAVA_SUBJECT_KEY tab to see sample code to instantiate a MongoCredential that uses GSSAPI and the selected property:

MongoCredential credential = MongoCredential.createGSSAPICredential(<db_username>);
credential = credential.withMechanismProperty(MongoCredential.SERVICE_NAME_KEY, "myService");

LoginContext loginContext = new LoginContext(<LoginModule implementation from JAAS config>);
loginContext.login();
Subject subject = loginContext.getSubject();
MongoCredential credential = MongoCredential.createGSSAPICredential(<db_username>);
credential = credential.withMechanismProperty(MongoCredential.JAVA_SUBJECT_KEY, subject);

Configure Caching Behavior

By default, the Java driver caches Kerberos tickets by MongoClient instance. If your deployment needs to frequently create and destroy MongoClient instances, you can change the default Kerberos ticket caching behavior to cache by process to improve performance.

To cache Kerberos tickets by process, you must use the MongoCredential authentication mechanism, as the connection string authentication mechanism does not support the JAVA_SUBJECT_PROVIDER mechanism property. If you would like to cache Kerberos tickets by process, select the MongoCredential tab to learn how to accomplish this.

To cache Kerberos tickets by process, you must specify the JAVA_SUBJECT_PROVIDER mechanism property and provide a KerberosSubjectProvider in your MongoCredential instance. The code to configure the Java driver to cache Kerberos tickets by process resembles the following:

/* all MongoClient instances sharing this instance of KerberosSubjectProvider
will share a Kerberos ticket cache */
String myLoginContext = "myContext";
MongoCredential credential = MongoCredential.createGSSAPICredential(<db_username>);
/* login context defaults to "com.sun.security.jgss.krb5.initiate"
if unspecified in KerberosSubjectProvider */
credential = credential.withMechanismProperty(MongoCredential.JAVA_SUBJECT_PROVIDER_KEY,
                                              new KerberosSubjectProvider(myLoginContext));

Note

On Windows, Oracle's JRE uses LSA rather than SSPI in its implementation of GSSAPI which limits interoperability with Windows Active Directory and implementations of single sign-on. For more information, see the following resources:

API Documentation

To learn more about any of the methods or types discussed on this page, see the following API documentation:

Back

LDAP (PLAIN)

In-Use Encryption