Authentication

In this guide, you can learn how to authenticate with MongoDB using the authentication mechanisms available in the MongoDB Community Edition. Authentication mechanisms are processes by which the driver and server confirm the identity of a client to ensure security before connecting.

MongoCredential

Include the following import statements:

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

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.

Default Authentication Mechanism

To create a credential that authenticates by using the default authentication mechanism, SCRAM-SHA-256, create a credential by 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);
MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
            builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
        .credential(credential)
        .build());

Or, you can use a connection string without explicitly specifying the authentication mechanism:

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

For challenge and response mechanisms, we recommend using the default authentication mechanism. This simplifies upgrades and ensures that the correct hashing algorithm is used.

SCRAM-Based Mechanisms

Salted Challenge-Response Authentication Mechanism (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 supports both SCRAM-SHA-1, which uses the SHA-1 hashing function, and SCRAM- SHA-256, which uses the SHA-256 hashing function.

SCRAM-SHA-256

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

Or, you can use a connection string that explicitly specifies authMechanism=SCRAM-SHA-256:

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

Or, you can use a connection string that explicitly specifies authMechanism=SCRAM-SHA-1:

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

MONGODB-CR

Important

MongoDB no longer supports the deprecated MongoDB Challenge-Response (MONGODB-CR) authentication mechanism. If your deployment has user credentials stored in a MONGODB-CR schema, you must upgrade to a SCRAM-based mechanism.

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

Or, you can use a connection string that explicitly specifies authMechanism=MONGODB-CR:

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

Note

After you upgrade the authentication schema from MONGODB-CR to SCRAM, MONGODB-CR credentials will fail to authenticate.

X.509

With the 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. 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);
MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
            builder.hosts(Arrays.asList(new ServerAddress("host1", 27017))))
        .credential(credential)
        .build());

Or, you can use a connection string that explicitly specifies authMechanism=MONGODB-X509:

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

See the Use x.509 Certificates to Authenticate Clients tutorial in the Server manual to learn more about determining the subject name from the certificate.

Back

Security

Enterprise Authentication