/ /

Configure SCRAM Authentication

Overview

Salted Challenge Response Authentication Mechanism (SCRAM) is the default authentication mechanism for MongoDB. The Scala driver supports the following SCRAM variants:

SCRAM-SHA-256: Uses the SHA-256 hashing algorithm and is the default mechanism for MongoDB 6.0 and later.
SCRAM-SHA-1: Uses the SHA-1 hashing algorithm.

You can use SCRAM to authenticate to MongoDB Atlas, MongoDB Enterprise Advanced, and MongoDB Community Edition.

Tip

SCRAM Mechanisms

To learn more about the SCRAM family of authentication mechanisms, see RFC 5802 and Salted Challenge Response Authentication Mechanism on Wikipedia.

For more information about the MongoDB implementation of SCRAM, see SCRAM in the MongoDB Server manual.

Code Placeholders

The code examples on this page use the following placeholders:

<db_username>: The MongoDB username of the user to authenticate.
<db_password>: The MongoDB password of the user to authenticate.
<hostname>: The network address of your MongoDB deployment.
<port>: The port number of your MongoDB deployment. If you omit this parameter, the driver uses the default port number (27017). You do not need a port number when connecting to a MongoDB Atlas cluster.
<authenticationDb>: The MongoDB database that contains the user's authentication data. If you omit this parameter, the driver uses the default value, admin.

To use the code examples, replace these placeholders with your own values.

Default Authentication Mechanism

The default authentication mechanism for MongoDB 6.0 and later is SCRAM-SHA-256. To use the default mechanism, select one of the following tabs:

To authenticate with a connection string, omit the authMechanism parameter:

val mongoClient = MongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=<authenticationDb>")

The MongoCredential class represents an authentication credential and includes static factory methods for each authentication mechanism. To authenticate with the MongoCredential class, use the createCredential() method:

val user = "<db_username>"          // the username
val source = "<authenticationDb>"   // the authentication database
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("<hostname>", <port>))))
    .credential(credential)
    .build())

SCRAM-SHA-256

To use this mechanism, featureCompatibilityVersion must be 4.0 or later. To specify the SCRAM-SHA-256 authentication mechanism, select one of the following tabs:

To authenticate with a connection string, set the authMechanism parameter to SCRAM-SHA-256:

val mongoClient = MongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=<authenticationDb>&authMechanism=SCRAM-SHA-256")

val user = "<db_username>"          // the username
val source = "<authenticationDb>"   // the authentication database
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("<hostname>", <port>))))
    .credential(credential)
    .build())

SCRAM-SHA-1

To specify the SCRAM-SHA-1 authentication mechanism, select one of the following tabs:

To authenticate with a connection string, set the authMechanism parameter to SCRAM-SHA-1:

val mongoClient = MongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=<authenticationDb>&authMechanism=SCRAM-SHA-1")

val user = "<db_username>"          // the username
val source = "<authenticationDb>"   // the authentication database
val password = ...                  // the password as a character array
val credential = MongoCredential.createScramSha1Credential(user, source, password)
val mongoClient = MongoClient(MongoClientSettings
    .builder()
    .applyToClusterSettings(builder =>
        builder.hosts(Collections.singletonList(ServerAddress("<hostname>", <port>))))
    .credential(credential)
    .build())

API Documentation

For more information about the methods and types on this page, see the following API documentation:

Back

Authentication

X.509