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

The page refers to the GSSAPI authentication mechanism instead of Kerberos because the driver authenticates by using the GSSAPI RFC-4652 SASL mechanism.

Specify Kerberos Authentication

The examples in this section show how to specify the GSSAPI authentication mechanism and use the following placeholder values:

<Kerberos principal>: Your URL-encoded principal name.
<hostname>: The network address of your MongoDB deployment, accessible by your client.
<port>: The port number of your MongoDB deployment. If you omit this parameter, the driver uses the default port number (27017).

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 in your a connection string, perform the following actions:

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

Note

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

The following example specifies the authentication mechanism in a connection string:

val connectionString = ConnectionString("<Kerberos principal>@<hostname>:<port>/?authSource=$external&authMechanism=GSSAPI")
val mongoClient = MongoClient.create(connectionString)

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

val credential = MongoCredential.createGSSAPICredential("<Kerberos principal>")
val settings = MongoClientSettings.builder()
        .applyToClusterSettings { builder ->
            builder.hosts(listOf(ServerAddress("<hostname>", <port>)))
        }
        .credential(credential)
        .build()
val mongoClient = MongoClient.create(settings)

Acquiring a Kerberos Ticket

In order to acquire a Kerberos ticket, the GSSAPI Java libraries require you to specify the realm and Key Distribution Center (KDC) system properties.

The following code shows sample values for these properties:

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

Additional Properties

You may need to specify one or more of the following additional 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 by 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 by using the format: <PROPERTY_NAME>:<value>.

Your code to instantiate a MongoClient using GSSAPI and additional properties resembles the following example:

val connectionString = ConnectionString("<Kerberos principal>@<hostname>:<port>/?authSource=$external&authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:myService")
val mongoClient = MongoClient.create(connectionString)

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 following 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:

val credential = MongoCredential.createGSSAPICredential("<Kerberos principal>")
    .withMechanismProperty(MongoCredential.SERVICE_NAME_KEY, "myService")

val loginContext = LoginContext("<LoginModule implementation from JAAS config>")
loginContext.login()
val subject: Subject = loginContext.subject
val credential = MongoCredential.createGSSAPICredential("<Kerberos principal>")
    .withMechanismProperty(MongoCredential.JAVA_SUBJECT_KEY, subject)

Ticket Caching

By default, the Kotlin 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. To view instructions, select the MongoCredential tab.

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

/* All MongoClient instances sharing this instance of KerberosSubjectProvider
will share a Kerberos ticket cache */
val myLoginContext = "myContext"
/* Login context defaults to "com.sun.security.jgss.krb5.initiate"
if unspecified in KerberosSubjectProvider */
val credential = MongoCredential.createGSSAPICredential("<Kerberos principal>")
    .withMechanismProperty(
        MongoCredential.JAVA_SUBJECT_PROVIDER_KEY,
        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. See the following articles for more information:

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 Kotlin Sync driver, see the Create a MongoClient guide.

API Documentation

To learn more about the classes and methods for authenticating your application with Kotlin Sync driver, see the following API documentation:

Back

LDAP (PLAIN)

In-Use Encryption