Enterprise Authentication Mechanisms
On this page
Overview
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:
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.
Specify an Authentication Mechanism
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:
Mechanisms
Kerberos (GSSAPI)
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 accessport
: 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:
To specify the GSSAPI authentication mechanism using a connection string:
Assign the
authMechanism
URL parameter to the valueGSSAPI
(optional) 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
.
The code to instantiate a MongoClient
resembles the following:
MongoClient mongoClient = MongoClients.create("<db_username>@<hostname>:<port>/?authSource=$external&authMechanism=GSSAPI");
To specify the GSSAPI authentication mechanism using the
MongoCredential
class, use the createGSSAPICredential()
method. The code to instantiate a MongoClient
resembles
the following:
MongoCredential credential = MongoCredential.createGSSAPICredential(<db_username>); MongoClient mongoClient = MongoClients.create( MongoClientSettings.builder() .applyToClusterSettings(builder -> builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>)))) .credential(credential) .build());
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 only specify the following GSSAPI properties 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 using the format:
<PROPERTY_NAME>:<value>
.
Your code to instantiate a MongoClient
using GSSAPI and additional
properties might resemble the following:
MongoClient mongoClient = MongoClients.create("<db_username>@<hostname>:<port>/?authSource=$external&authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:myService");
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:
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:
MongoCredential credential = MongoCredential.createGSSAPICredential(<db_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(<db_username>); credential = credential.withMechanismProperty(MongoCredential.JAVA_SUBJECT_KEY, subject);
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.
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. If you would like to cache Kerberos tickets by process, select the MongoCredential
tab to learn how to accomplish this.
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 Java driver to cache Kerberos tickets
by process resembles the following:
/* all MongoClient instances sharing this instance of KerberosSubjectProvider will share a Kerberos ticket cache */ String myLoginContext = "myContext"; MongoCredential credential = MongoCredential.createGSSAPICredential(<db_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));
LDAP (PLAIN)
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 usernamepassword
: your LDAP user's passwordhostname
: network address of your MongoDB deployment that your client can accessport
: 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:
To specify the LDAP (PLAIN) authentication mechanism using a connection string:
Assign the
authMechanism
URL parameter to the valuePLAIN
(optional) Assign the
authSource
URL parameter to the value$external
Note
If you specify the PLAIN
mechanism, you cannot assign
authSource
to any value other than $external
.
The code to instantiate a MongoClient
resembles the following:
MongoClient mongoClient = MongoClients.create("<db_username>:<db_password>@<hostname>:<port>/?authSource=$external&authMechanism=PLAIN");
To specify the LDAP (PLAIN) authentication mechanism using the
MongoCredential
class, use the createPlainCredential()
method. The code to instantiate a MongoClient
resembles the following:
MongoCredential credential = MongoCredential.createPlainCredential(<db_username>, "$external", <db_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 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 from 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.
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://<db_username>@<hostname>:<port>/?" + "?authMechanism=MONGODB-OIDC" + "&authMechanismProperties=ENVIRONMENT:azure,TOKEN_RESOURCE:<percent-encoded audience>");
Replace the <db_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("<db_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 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 from 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.
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://<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 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());