Authentication

The Java driver supports all MongoDB authentication mechanisms, including those only available in the MongoDB Enterprise Edition.

MongoCredential

import com.mongodb.MongoCredential;

New MongoClient API (since 3.7):

import com.mongodb.ConnectionString;
import com.mongodb.client.MongoClients;
import com.mongodb.client.MongoClient;

Legacy MongoClient API:

import com.mongodb.MongoClient;
import com.mongodb.ConnectionString;

An authentication credential is represented as an instance of the MongoCredential class. The MongoCredential class includes static factory methods for each of the supported authentication mechanisms.

You can also use a ConnectionString and pass it to a MongoClient() constructor that takes a ConnectionString parameter.

Default Authentication Mechanism

In MongoDB 3.0, MongoDB changed the default authentication mechanism from MONGODB-CR to SCRAM-SHA-1. In MongoDB 4.0 support for the deprecated MONGODB-CR mechanism was removed and SCRAM-SHA-256 support was added.

To create a credential that will authenticate using the default authentication mechanism regardless of server version, create a credential using the createCredential static factory method:

String user;     // the user name
String source;   // the source where the user is defined
char[] password; // the password as a character array
// ...
MongoCredential credential = MongoCredential.createCredential(user, source, password);

and then construct a MongoClient with that credential. Using the new (since 3.7) MongoClient API:

MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder()
                .applyToClusterSettings(builder ->
                        builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
                .credential(credential)
                .build());

or using the legacy MongoClient API:

MongoClient mongoClient = new MongoClient(
        MongoClientSettings.builder()
                .applyToClusterSettings(builder ->
                        builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
                .credential(credential)
                .build());

Or use a connection string without explicitly specifying the authentication mechanism. Using the new MongoClient API:

MongoClient mongoClient = MongoClients.create("mongodb://user1:pwd1@host1/?authSource=db1");

or using the legacy MongoClient API:

MongoClient mongoClient = new MongoClient("mongodb://user1:pwd1@host1/?authSource=db1");

For challenge and response mechanisms, using the default authentication mechanism is the recommended approach as it will make upgrading from MongoDB 2.6 to MongoDB 3.0 seamless, even after upgrading the authentication schema. For MongoDB 4.0 users it is also recommended as the supported authentication mechanisms are checked and the correct hashing algorithm is used.

SCRAM

Salted Challenge Response Authentication Mechanism (SCRAM) has been the default authentication mechanism for MongoDB since 3.0. SCRAM is based on the IETF RFC 5802 standard that defines best practices for implementation of challenge-response mechanisms for authenticating users with passwords.

MongoDB 3.0 introduced support for SCRAM-SHA-1 which uses the SHA-1 hashing function. MongoDB 4.0 introduced support for SCRAM-SHA-256 which uses the SHA-256 hashing function.

SCRAM-SHA-256

Requires MongoDB 4.0 and featureCompatibilityVersion to be set to 4.0.

To explicitly create a credential of type SCRAM-SHA-256, use the createScramSha256Credential method:

String user;     // the user name
String source;   // the source where the user is defined
char[] password; // the password as a character array
// ...
MongoCredential credential = MongoCredential.createScramSha256Credential(user, source, password);

and then construct a MongoClient with that credential. Using the new (since 3.7) MongoClient API:

MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder()
                .applyToClusterSettings(builder ->
                        builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
                .credential(credential)
                .build());

or using the legacy MongoClient API:

MongoClient mongoClient = new MongoClient(
        MongoClientSettings.builder()
                .applyToClusterSettings(builder ->
                        builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
                .credential(credential)
                .build());

Or use a connection string that explicitly specifies the authMechanism=SCRAM-SHA-256. Using the new MongoClient API:

MongoClient mongoClient = MongoClients.create("mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=SCRAM-SHA-256");

or using the legacy MongoClient API:

MongoClient mongoClient = new MongoClient("mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=SCRAM-SHA-256");

SCRAM-SHA-1

To explicitly create a credential of type SCRAM-SHA-1, use the createScramSha1Credential method:

String user;     // the user name
String source;   // the source where the user is defined
char[] password; // the password as a character array
// ...
MongoCredential credential = MongoCredential.createScramSha1Credential(user, source, password);

and then construct a MongoClient with that credential. Using the new (since 3.7) MongoClient API:

MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder()
                .applyToClusterSettings(builder ->
                        builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
                .credential(credential)
                .build());

or using the legacy MongoClient API:

MongoClient mongoClient = new MongoClient(
        MongoClientSettings.builder()
                .applyToClusterSettings(builder ->
                        builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
                .credential(credential)
                .build());

Or use a connection string that explicitly specifies the authMechanism=SCRAM-SHA-1. Using the new MongoClient API:

MongoClient mongoClient = MongoClients.create("mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=SCRAM-SHA-1");

or using the legacy MongoClient API:

MongoClient mongoClient = new MongoClient("mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=SCRAM-SHA-1");

MONGODB-CR

To explicitly create a credential of type MONGODB-CR use the createMongCRCredential static factory method:

String user; // the user name
String database; // the name of the database in which the user is defined
char[] password; // the password as a character array
// ...
MongoCredential credential = MongoCredential.createMongoCRCredential(user, database, password);

and then construct a MongoClient with that credential. Using the new (since 3.7) MongoClient API:

MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder()
                .applyToClusterSettings(builder ->
                        builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
                .credential(credential)
                .build());

or using the legacy MongoClient API:

MongoClient mongoClient = new MongoClient(
        MongoClientSettings.builder()
                .applyToClusterSettings(builder ->
                        builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
                .credential(credential)
                .build());

Or use a connection string that explicitly specifies the authMechanism=MONGODB-CR. Using the new MongoClient API:

MongoClient mongoClient = MongoClients.create("mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=MONGODB-CR");

or using the legacy MongoClient API:

MongoClient mongoClient = new MongoClient("mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=MONGODB-CR");

X.509

With X.509 mechanism, MongoDB uses the X.509 certificate presented during SSL negotiation to authenticate a user whose name is derived from the distinguished name of the X.509 certificate.

X.509 authentication requires the use of SSL connections with certificate validation and is available in MongoDB 2.6 and later. To create a credential of this type use the createMongoX509Credential static factory method:

String user;     // The X.509 certificate derived user name, e.g. "CN=user,OU=OrgUnit,O=myOrg,..."
// ...
MongoCredential credential = MongoCredential.createMongoX509Credential(user);

and then construct a MongoClient with that credential. Using the new (since 3.7) MongoClient API:

MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder()
                .applyToClusterSettings(builder ->
                        builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
                .credential(credential)
                .build());

or using the legacy MongoClient API:

MongoClient mongoClient = new MongoClient(
        MongoClientSettings.builder()
                .applyToClusterSettings(builder ->
                        builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
                .credential(credential)
                .build());

Or use a connection string that explicitly specifies the authMechanism=MONGODB-X509. Using the new MongoClient API:

MongoClient mongoClient = MongoClients.create("mongodb://subjectName@host1/?authMechanism=MONGODB-X509&ssl=true");

or using the legacy MongoClient API:

MongoClient mongoClient = new MongoClient("mongodb://subjectName@host1/?authMechanism=MONGODB-X509&ssl=true");

See the MongoDB server x.509 tutorial for more information about determining the subject name from the certificate.

MONGODB-AWS

The MONGODB-AWS authentication mechanism uses your Amazon Web Services Identity and Access Management (AWS IAM) credentials to authenticate your user.

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

• username - value of your AWS_ACCESS_KEY_ID
• password - value your AWS_SECRET_ACCESS_KEY
• hostname - network address of your MongoDB server, accessible by your client
• port - port number of your MongoDB server
• authenticationDb - MongoDB database that contains your user’s authentication data. If you omit this parameter, the driver uses the default value admin.
• awsSessionToken - value of your AWS_SESSION_TOKEN (optional)

Connection String

To specify the mechanism using a connection string, assign the authMechanism parameter the value MONGODB-AWS in your connection string. Your code to instantiate a MongoClient should resemble the following:

MongoClient mongoClient = MongoClients.create("mongodb://<username>:<password>@<hostname>:<port>/?authSource=<authenticationDb>&authMechanism=MONGODB-AWS");

If you need to specify an AWS session token, include it in the authMechanismProperties parameter as follows using the format AWS_SESSION_TOKEN:<awsSessionToken>. Your code to instantiate a MongoClient with a session token should resemble the following:

MongoClient mongoClient = MongoClients.create("mongodb://<username>:<password>@<hostname>:<port>/?authSource=<authenticationDb>&authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<awsSessionToken>");

MongoCredential

To specify the mechanism using the MongoCredential class, use the createAwsCredential() method. Your code to instantiate a MongoClient should resemble the following:

MongoCredential credential = MongoCredential.createAwsCredential("<username>", "<password>".toCharArray());

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

If you need to specify an AWS session token, you can add it using one of the following choices:

Specify your AWS Session Token in a Connection String

If you prefer to pass the AWS session token in the connection string, you specify your authentication mechanism in the authMechanism parameter and your session token in the authMechanismProperties parameter. Then, add it to your MongoClientSettings by calling the applyConnectionString()” >}}) method as follows:

MongoCredential credential = MongoCredential.createAwsCredential("<username>", "<password>".toCharArray());
String connectionString = "mongodb://<hostname>:<port>/?authSource=<authenticationDb>&authMechanism=MONGODB-AWS&authMechanismProperties=AWS_SESSION_TOKEN:<awsSessionToken>");

MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder()
        .applyConnectionString(connectionString)
        .credential(credential)
        .build());

Specify your AWS Session Token in a MongoCredential

You can include your AWS session token in your MongoCredential instance by specifying it in a call to the withMechanismProperty() method as shown below:

MongoCredential.createAwsCredential("<username>", "<password>".toCharArray()) .withMechanismProperty("AWS_SESSION_TOKEN", "<awsSessionToken>")

Specify your AWS Session Token in an Environment Variable

In your client execution environment, set an environment variable called AWS_SESSION_TOKEN and assign your token to it. The value is automatically picked up by your MongoClient when you specify the MONGODB-AWS authentication mechanism.

Kerberos (GSSAPI)

MongoDB Enterprise supports proxy authentication through Kerberos service. To create a credential of type Kerberos (GSSAPI), use the createGSSAPICredential static factory method:

String user;   // The Kerberos user name, including the realm, e.g. "user1@MYREALM.ME"
// ...
MongoCredential credential = MongoCredential.createGSSAPICredential(user);

and then construct a MongoClient with that credential. Using the new (since 3.7) MongoClient API:

MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder()
                .applyToClusterSettings(builder ->
                        builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
                .credential(credential)
                .build());

or using the legacy MongoClient API:

MongoClient mongoClient = new MongoClient(
        MongoClientSettings.builder()
                .applyToClusterSettings(builder ->
                        builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
                .credential(credential)
                .build());

Or use a connection string that explicitly specifies the authMechanism=GSSAPI. Using the new MongoClient API:

MongoClient mongoClient = MongoClients.create("mongodb://username%40REALM.ME@host1/?authMechanism=GSSAPI");

or using the legacy MongoClient API:

MongoClient mongoClient = new MongoClient("mongodb://username%40REALM.ME@host1/?authMechanism=GSSAPI");

To successfully authenticate via Kerberos, the application typically must specify several system properties so that the underlying GSSAPI Java libraries can acquire a Kerberos ticket:

java.security.krb5.realm=MYREALM.ME
java.security.krb5.kdc=mykdc.myrealm.me

Depending on the Kerberos setup, additional property specifications may be required, either via the application code or, in some cases, the withMechanismProperty() method of the MongoCredential instance:

• SERVICE_NAME

• CANONICALIZE_HOST_NAME

• JAVA_SUBJECT

• JAVA_SASL_CLIENT_PROPERTIES

For example, to specify the SERVICE_NAME property via the MongoCredential object:

credential = credential.withMechanismProperty(MongoCredential.SERVICE_NAME_KEY, "othername");

Or via the ConnectionString:

mongodb://username%40MYREALM.com@myserver/?authMechanism=GSSAPI&authMechanismProperties=SERVICE_NAME:othername

LDAP (PLAIN)

MongoDB Enterprise supports proxy authentication through a Lightweight Directory Access Protocol (LDAP) service. To create a credential of type LDAP use the createPlainCredential static factory method:

String user;          // The LDAP user name
char[] password;      // The LDAP password
// ...
MongoCredential credential = MongoCredential.createPlainCredential(user, "$external", password);

and then construct a MongoClient with that credential. Using the new (since 3.7) MongoClient API:

MongoClient mongoClient = MongoClients.create(
        MongoClientSettings.builder()
                .applyToClusterSettings(builder ->
                        builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
                .credential(credential)
                .build());

or using the legacy MongoClient API:

MongoClient mongoClient = new MongoClient(
        MongoClientSettings.builder()
                .applyToClusterSettings(builder ->
                        builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
                .credential(credential)
                .build());

Or use a connection string that explicitly specifies the authMechanism=PLAIN. Using the new MongoClient API:

MongoClient mongoClient = MongoClients.create("mongodb://user1@host1/?authSource=$external&authMechanism=PLAIN");

or using the legacy MongoClient API:

MongoClient mongoClient = new MongoClient("mongodb://user1@host1/?authSource=$external&authMechanism=PLAIN");