/ /

Authentication

Docs Home

/ /

Java Reactive Streams Driver

Java Reactive Streams Driver

Authentication

Kerberos (GSSAPI) Authentication

Overview

The Generic Security Services API (GSSAPI) authentication mechanism allows you to authenticate to a Kerberos service by specifying your Kerberos principal name.

Note

Terminology

The page uses GSSAPI when referring to the authentication mechanism and Kerberos when referring to the underlying protocol or service. The driver authenticates by using the GSSAPI RFC-4752 SASL mechanism, which is built on top of the Kerberos protocol.

Specify Kerberos Authentication

The following sections contain code examples that use the following placeholder values:

<username>: Your URL-encoded principal name, such as "username%40REALM.ME"
<hostname>: The network address of your MongoDB deployment, accessible by your client
<port>: The port number of your MongoDB deployment

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

The following example authenticates to GSSAPI by using a connection string:

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

To specify the GSSAPI authentication mechanism by using the MongoCredential class, call the createGSSAPICredential() method, as shown in the following example:

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

Acquire a Kerberos Ticket

To acquire a Kerberos ticket, the GSSAPI Java libraries require you to specify the realm and Key Distribution Center (KDC) JVM system properties. The following example shows how to set these properties:

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

Set Additional Properties

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

SERVICE_NAME
CANONICALIZE_HOST_NAME
JAVA_SUBJECT
JAVA_SASL_CLIENT_PROPERTIES
JAVA_SUBJECT_PROVIDER

Select the Connection String or the MongoCredential tab below for instructions and sample code for specifying these properties:

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

The following example authenticates to GSSAPI and specifies the SERVICE_NAME property:

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

Important

You can specify the following GSSAPI properties only on a MongoCredential instance:

JAVA_SUBJECT
JAVA_SASL_CLIENT_PROPERTIES
JAVA_SUBJECT_PROVIDER

Select the MongoCredential tab to learn how to specify these properties.

To specify 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:

The following example authenticates to GSSAPI and specifies the SERVICE_NAME_KEY constant:

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

The JAVA_SUBJECT_KEY property requires a javax.security.auth.Subject object. To retrieve a Subject, you must first authenticate through the Java Authentication and Authorization Service (JAAS) by using a LoginContext. The following example shows this configuration:

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

Configure Ticket Caching

By default, the Java Reactive Streams driver caches Kerberos tickets by the MongoClient instance that created them. If your deployment frequently creates and destroys MongoClient instances, you can improve performance by changing the default Kerberos ticket caching behavior to cache by process.

Important

You must use the MongoCredential class to change the default caching behavior, because the connection string authentication mechanism does not support the JAVA_SUBJECT_PROVIDER mechanism property.

To cache Kerberos tickets by process, specify the JAVA_SUBJECT_PROVIDER mechanism property and provide a KerberosSubjectProvider in your MongoCredential instance, as shown in the following example:

/* All MongoClient instances sharing this instance of KerberosSubjectProvider
will share a Kerberos ticket cache */
String myLoginContext = "myContext";
MongoCredential credential = MongoCredential
    .createGSSAPICredential("<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 Local Security Authority (LSA) rather than Security Support Provider Interface (SSPI) in its implementation of GSSAPI. This limits interoperability with Windows Active Directory and implementations of single sign-on. To learn more, see the following resources:

Additional Information

To learn more about authenticating to MongoDB, see Authentication in the MongoDB Server manual.

To learn more about creating a MongoClient object by using the Java Reactive Streams driver, see the Connect to MongoDB guide.

API Documentation

To learn more about the classes and methods mentioned in this guide, see the following API documentation:

Back

LDAP (PLAIN)

Enterprise Authentication