/ /

Kerberos (GSSAPI) Authentication

Overview

The Generic Security Services API (GSSAPI) authentication mechanism allows you to authenticate to a Kerberos service by specifying your 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 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 to view instructions and a code example:

To specify the GSSAPI authentication mechanism in your 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 mongoClient = MongoClient(
  "mongodb://<Kerberos principal>@<hostname>:<port>/?authSource=$external&authMechanism=GSSAPI"
)

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 mongoClient = MongoClient(MongoClientSettings
    .builder()
    .applyToClusterSettings(builder =>
        builder.hosts(List(new ServerAddress("<hostname>", <port>)).asJava))
    .credential(credential)
    .build())

Acquiring a Kerberos Ticket

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

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

Important

You can specify the following GSSAPI properties only 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 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:

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

val credential = MongoCredential.createGSSAPICredential("<Kerberos principal>")
    .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:

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

Ticket Caching

By default, the Scala 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 */
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,
        new KerberosSubjectProvider(myLoginContext)
    )

Note

On Windows, Oracle's JRE uses LSA rather than SSPI in its implementation of GSSAPI. This behavior 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 Scala driver, see the Create a MongoClient guide.

API Documentation

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

Back

LDAP

In-Use Encryption