SCRAM Authentication

Overview

Salted Challenge Response Authentication Mechanism (SCRAM) is a family of authentication mechanisms that use a challenge-response mechanism to authenticate the user. SCRAM-SHA-256, which uses the SHA-256 algorithm to hash your password, is the default authentication mechanism in MongoDB Server version 4.0 and later. SCRAM-SHA-1, which uses the SHA-1 algorithm, is the default authentication mechanism in MongoDB Server versions earlier than 4.0.

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.

Specify SCRAM-SHA-256 Authentication

SCRAM-SHA-256, as defined by RFC 7677, encrypts your username and password with the SHA-256 algorithm to authenticate your user. This is the default authentication mechanism.

The examples in this section show how to specify this default authentication mechanism and use the following placeholder values:

db_username: Your MongoDB database username.
db_password: Your MongoDB database user's password.
hostname: The network address of your MongoDB deployment, open to your client.
port: The port number of your MongoDB deployment.
authenticationDb: The MongoDB database that contains your user's authentication data. If you omit this parameter, the driver uses the default value admin.

Select the Connection String or the MongoCredential tab below for instructions and sample code for specifying this authentication mechanism:

To specify the default authentication mechanism by using a connection string, omit the mechanism as shown in the following example:

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

To specify the default authentication mechanism by using the MongoCredential class, use the createCredential() method as shown in the following example:

val credential = MongoCredential.createCredential(
    "<db_username>", "<authenticationDb>", "<db_password>".toCharArray()
)
val settings = MongoClientSettings.builder()
        .applyToClusterSettings { builder: ClusterSettings.Builder ->
            builder.hosts(
                listOf(ServerAddress("<hostname>", <port>))
            )
        }
        .credential(credential)
        .build()
val mongoClient = MongoClient.create(settings)

Alternatively, you can explicitly specify the SCRAM-SHA-256 authentication mechanism. Select the Connection String or the MongoCredential tab below for instructions and sample code for specifying this authentication mechanism:

To specify the SCRAM-SHA-256 authentication mechanism by using a connection string, assign the authMechanism parameter the value SCRAM-SHA-256 in your connection string as shown in the following example:

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

To specify the default authentication mechanism by using the MongoCredential class, use the createScramSha256Credential() method as shown in the following example:

val credential = MongoCredential.createScramSha256Credential(
    "<db_username>", "<authenticationDb>", "<db_password>".toCharArray()
)
val settings = MongoClientSettings.builder()
        .applyToClusterSettings { builder: ClusterSettings.Builder ->
            builder.hosts(
                listOf(ServerAddress("<hostname>", <port>))
            )
        }
        .credential(credential)
        .build()
val mongoClient = MongoClient.create(settings)

Specify SCRAM-SHA-1 Authentication

SCRAM-SHA-1, as defined by RFC 5802, encrypts your username and password with the SHA-1 algorithm to authenticate your user.

The examples in this section show how to specify this authentication mechanism and use the following placeholder values:

db_username: Your MongoDB database username.
db_password: Your MongoDB database user's password.
hostname: The network address of your MongoDB deployment, open to your client.
port: The port number of your MongoDB deployment.
authenticationDb: The MongoDB database that contains your user's authentication data. If you omit this parameter, the driver uses the default value admin.

Select the Connection String or the MongoCredential tab below for instructions and sample code for specifying the SCRAM-SHA-1 authentication mechanism:

To specify the SCRAM-SHA-1 authentication mechanism by using a connection string, assign the authMechanism parameter the value SCRAM-SHA-1 in your connection string as shown in the following example:

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

To specify the default authentication mechanism by using the MongoCredential class, use the createScramSha1Credential() method as shown in the following example:

val credential = MongoCredential.createScramSha1Credential(
    "<db_username>", "<authenticationDb>", "<db_password>".toCharArray()
)
val settings = MongoClientSettings.builder()
        .applyToClusterSettings { builder: ClusterSettings.Builder ->
            builder.hosts(
                listOf(ServerAddress("<hostname>", <port>))
            )
        }
        .credential(credential)
        .build()
val mongoClient = MongoClient.create(settings)

Additional Information

To learn more about authenticating to MongoDB, see Authentication in the MongoDB Server manual.

To learn more about creating a MongoClient object by using the Kotlin Sync driver, see the Create a MongoClient guide.

Back

Authentication

X.509