Docs Menu
Docs Home
/ / /
Java Sync Driver
/

Enterprise Authentication Mechanisms

On this page

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

In this guide, you can learn how to authenticate with MongoDB using each authentication mechanism available exclusively in the MongoDB Enterprise Edition.

You can use the following mechanisms with the latest version of MongoDB Enterprise Edition:

  • Kerberos (GSSAPI)

  • LDAP (PLAIN)

  • MONGODB-OIDC

To authenticate using another mechanism, see the Authentication Mechanisms guide. For more information on establishing a connection to your MongoDB cluster, read our Connection Guide.

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

  • A connection string

  • A MongoCredential factory method

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

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

Alternatively, you can 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, you need to use the MongoClientSettings.Builder class to configure your connection settings when constructing your MongoClient. Select the MongoCredential tab to see the syntax for authenticating using a MongoCredential.

For more information about these classes and methods, see the following API documentation:

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.

The following code snippets show how to specify the authentication mechanism, using 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 the MongoCredential tab below for instructions and sample code for specifying this authentication mechanism:

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

By default, the Java 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.

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:

Available in MongoDB Enterprise Edition 3.4 and later.

You can authenticate to a Lightweight Directory Access Protocol (LDAP) server 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.

You can specify this authentication mechanism by setting the authMechanism parameter to PLAIN and including your LDAP username and password in the connection string.

The following code snippets show how to specify the authentication mechanism, using the following placeholders:

  • username: your LDAP username

  • 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 the MongoCredential tab below for instructions and sample code for specifying this authentication mechanism:

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.

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 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 tab to see the corresponding syntax.

If your application runs on a GCP VM, or otherwise uses the GCP Instance Metadata Service, you can authenticate to MongoDB by using Java 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. Select the Connection String or MongoCredential tab to see the corresponding syntax.

The Java 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());
← Authentication Mechanisms