/ /

Kotlin Coroutine Driver

Kotlin Coroutine Driver

Authentication

Kerberos (GSSAPI) Authentication

Overview

The Generic Security Services API (GSSAPI) authentication mechanism allows the user to authenticate to a Kerberos service using the user's principal name.

Note

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

Code Placeholders

The code examples on this page use the following placeholders:

Kerberos principal - your URL-encoded principal name, e.g. "username%40REALM.ME"
hostname - network address of your MongoDB server, accessible by your client
port - port number of your MongoDB server

Authenticate with GSSAPI

To specify the GSSAPI authentication mechanism by using a connection string, assign the authMechanism URL parameter to the value GSSAPI Then, optionally 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.

Your code to instantiate a MongoClient should resemble the following:

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. Your code to instantiate a MongoClient should resemble the following:

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)

In order 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

You might 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 specify the following GSSAPI properties only by using the MongoCredential:

JAVA_SUBJECT
JAVA_SASL_CLIENT_PROPERTIES
JAVA_SUBJECT_PROVIDER

The following example shows how to specify the additional properties:

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:

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 property name constants defined in the MongoCredential class:

The following example instantiates a MongoCredential that uses GSSAPI and the the SERVICE_NAME_KEY:

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

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 specify the JAVA_SUBJECT_PROVIDER mechanism property and provide a KerberosSubjectProvider in your MongoCredential instance. The code to configure the Kotlin driver to cache Kerberos tickets by process should resemble the following:

/* 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:

Back

LDAP (PLAIN)

In-Use Encryption