Authentication Mechanisms

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

MongoCredential

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

The default authentication mechanism for MongoDB 6.0 and later is SCRAM-SHA-256.

To create a credential that authenticates by using the default authentication mechanism, regardless of server version, create a credential by using the createCredential() static factory method:

val user = "<db_username>"     // the username
val source = "<source>"     // the source where the user is defined
val password = ...          // the password as a character array
val credential = MongoCredential.createCredential(user, source, password)
val mongoClient = MongoClient(MongoClientSettings
    .builder()
    .applyToClusterSettings(builder =>
        builder.hosts(Collections.singletonList(ServerAddress("localhost", 27017))))
    .credential(credential)
    .build())

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

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

SCRAM-Based Mechanisms

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.

SCRAM-SHA-256

Using this mechanism requires featureCompatibilityVersion to be set to 4.0 or a later version.

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

val user = "<db_username>"     // the username
val source = "<source>"     // the source where the user is defined
val password = ...          // the password as a character array
val credential = MongoCredential.createScramSha256Credential(user, source, password)
val mongoClient = MongoClient(MongoClientSettings
    .builder()
    .applyToClusterSettings(builder =>
        builder.hosts(Collections.singletonList(ServerAddress("localhost", 27017))))
    .credential(credential)
    .build())

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

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

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:

val credential = MongoCredential.createMongoX509Credential()
val mongoClient = MongoClient(MongoClientSettings
    .builder()
    .applyToClusterSettings(builder =>
        builder.hosts(Collections.singletonList(ServerAddress("localhost", 27017))))
    .credential(credential)
    .build())

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

val mongoClient = MongoClient("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 using x.509 certificates in your application.

Back

Security

In-Use Encryption