Enterprise Authentication Mechanisms

On this page

Overview

Specify an Authentication Mechanism
Mechanisms
Kerberos (GSSAPI)
LDAP (PLAIN)
MONGODB-OIDC

Overview

MongoDB Enterprise Edition includes authentication mechanisms that aren't available in MongoDB Community Edition. In this guide, you can learn how to authenticate to MongoDB by using these authentication mechanisms. To learn about the other authentication mechanisms available in MongoDB, see the Authentication Mechanisms guide.

Specify an Authentication Mechanism

You can specify your authentication mechanism and credentials when connecting to MongoDB by using either of the following:

Connection string
MongoCredential factory method

A connection string (also known as a connection URI) specifies how to connect and authenticate to your MongoDB cluster.

To authenticate by using a connection string, include your settings in your connection string, then pass it to the MongoClients.create() method to instantiate your MongoClient. Select the Connection String tab in the following sections to see the syntax for authenticating by using a connection string.

You can also use the MongoCredential class to specify your authentication details. The MongoCredential class contains static factory methods that construct instances containing your authentication mechanism and credentials. When you use the MongoCredential helper class, use the MongoClientSettings.Builder class to configure your connection settings. Select the MongoCredential tab in the following sections to see the syntax for authenticating using a MongoCredential.

Mechanisms

Kerberos (GSSAPI)

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

The following sections contain code examples that use the following placeholders:

username: your URL-encoded principal name, such as "username%40REALM.ME"
hostname: network address of your MongoDB deployment that your client can access
port: port number of your MongoDB deployment

Select the Connection String or MongoCredential tabs to see the corresponding syntax.

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());

To acquire a Kerberos ticket, the GSSAPI Java libraries require you to specify the realm and Key Distribution Center (KDC) system properties. You can set these settings as shown 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 through the MongoCredential class:

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, include the property in the connection string as a URL parameter in the format: <PROPERTY_NAME>:<value>.

The following example authenticates to GSSAPI and specifies additional properties:

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

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:

Select the SERVICE_NAME_KEY or JAVA_SUBJECT_KEY tab to see how to specify the corresponding property:

MongoCredential credential = MongoCredential
    .createGSSAPICredential("<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("<username>");
credential = credential
    .withMechanismProperty(MongoCredential.JAVA_SUBJECT_KEY, subject);

By default, the Java Reactive Streams driver caches Kerberos tickets by MongoClient instance. If your deployment frequently creates and destroys 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, because the connection string authentication mechanism does not support the JAVA_SUBJECT_PROVIDER mechanism property. Select the MongoCredential tab to learn how to cache Kerberos tickets by process.

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 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 resources for more information:

LDAP (PLAIN)

You can authenticate to a Lightweight Directory Access Protocol (LDAP) server by using your directory server username and password.

Tip

The authentication mechanism is named PLAIN instead of LDAP since it authenticates using the PLAIN Simple Authentication and Security Layer (SASL) defined in RFC-4616.

The following sections contain code examples that use the following placeholders:

ldap_username: your LDAP username
ldap_password: your LDAP user's password
hostname: network address of your MongoDB deployment that your client can access
port: port number of your MongoDB deployment

Select the Connection String or MongoCredential tabs to see the corresponding syntax.

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

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

MongoCredential credential = MongoCredential
    .createPlainCredential(<ldap_username>, "$external", <ldap_password>);
MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
                builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
        .credential(credential)
        .build());

MONGODB-OIDC

Important

The MONGODB-OIDC authentication mechanism requires MongoDB Server v7.0 or later running on a Linux platform.

The following sections describe how to use the MONGODB-OIDC authentication mechanism to authenticate to various platforms.

For more information about the MONGODB-OIDC authentication mechanism, see OpenID Connect Authentication and MongoDB Server Parameters in the MongoDB Server manual.

Azure IMDS

If your application runs on an Azure VM, or otherwise uses the Azure Instance Metadata Service (IMDS), you can authenticate to MongoDB by using the Java Reactive Streams driver's built-in Azure support.

You can specify Azure IMDS OIDC authentication either by using a MongoCredential or as part of the connection string.

Select the Connection String or MongoCredential tabs to see the corresponding syntax.

Replace the <username> placeholder with the client ID or application ID of the Azure managed identity or enterprise application. Replace the <percent-encoded audience> placeholder in the following code with the percent-encoded value of the audience server parameter configured on your MongoDB deployment.

The comma (,) character and its encoding (%2C) are reserved, and using these characters in a value causes the driver to interpret commas as delimiters of key-value pairs. You must specify values that contain commas in a MongoCredential instance, as demonstrated in the MongoCredential tab.

MongoClient mongoClient = MongoClients.create(
            "mongodb://<username>@<hostname>:<port>/?" + 
            "?authMechanism=MONGODB-OIDC" +
            "&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:<percent-encoded audience>");

Replace the <username> placeholder with the client ID or application ID of the Azure managed identity or enterprise application. Replace the <audience> placeholder with the value of the audience server parameter configured on your MongoDB deployment.

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

GCP IMDS

If your application runs on a Google Compute Engine VM, or otherwise uses the GCP Instance Metadata Service, you can authenticate to MongoDB by using the Java Reactive Streams driver's built-in GCP support.

You can specify GCP IMDS OIDC authentication either by using a MongoCredential or as part of the connection string.

The following sections contain code examples that use the following placeholders:

hostname: network address of your MongoDB deployment that your client can access
port: port number of your MongoDB deployment

Select the Connection String or MongoCredential tabs to see the corresponding syntax.

Replace the <percent-encoded audience> placeholder in the following code with the percent-encoded value of the audience server parameter configured on your MongoDB deployment.

MongoClient mongoClient = MongoClients.create(
    "mongodb://<hostname>:<port>/?" +
    "authMechanism=MONGODB-OIDC" +
    "&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:<percent-encoded audience>");

Replace the <audience> placeholder with the value of the audience server parameter configured on your MongoDB deployment.

MongoCredential credential = MongoCredential.createOidcCredential()
            .withMechanismProperty("ENVIRONMENT", "gcp")
            .withMechanismProperty("TOKEN_RESOURCE", "<audience>");
   
MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
                builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
        .credential(credential)
        .build());

Custom Callback

The Java Reactive Streams driver doesn't offer built-in support for all platforms, including Azure Functions and Azure Kubernetes Service (AKS). Instead, you must define a custom callback to use OIDC to authenticate from these platforms. To do so, use the "OIDC_CALLBACK" authentication property, as shown in the following code example:

MongoCredential credential = MongoCredential.createOidcCredential(null)
    .withMechanismProperty("OIDC_CALLBACK", (context) ->  {
       String accessToken = ...
       return new OidcCallbackResult(accessToken);
});

The value of the "OIDC_CALLBACK" property must be a lambda or other implementation of the OidcCallback functional interface that accepts an OidcCallbackContext as a parameter and returns an OidcCallbackResult.

The following example uses an example callback to retrieve an OIDC token from a file named "access-token.dat" in the local file system:

MongoCredential credential = MongoCredential.createOidcCredential(null)
      .withMechanismProperty("OIDC_CALLBACK", (context) ->  {
         string accessToken = new String(Files.readAllBytes(Paths.get("access-token.dat"));
         return new OidcCallbackResult(accessToken);
      });
   MongoClient mongoClient = MongoClients.create(
       MongoClientSettings.builder()
           .applyToClusterSettings(builder ->
                   builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
           .credential(credential)
           .build());

Back

Authentication

In-Use Encryption