/ /

Authentication

Docs Home

/ /

Kotlin Coroutine Driver

Kotlin Coroutine Driver

Authentication

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.

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 - your MongoDB database username.
db_password - your MongoDB database user's password.
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.

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

Authenticate with SCRAM-SHA-256

Select the Connection String or the MongoCredential tab below for instructions and sample code to specify the SCRAM-SHA-256 authentication mechanism.

To specify the default authentication mechanism by using a connection string, omit the mechanism. Your code to instantiate a MongoClient should resemble the following:

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. Your code to instantiate a MongoClient should resemble the following:

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)

You can also explicitly specify the SCRAM-SHA-256 authentication mechanism, as shown in the following code snippets:

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. Your code to instantiate a MongoClient should resemble the following:

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

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

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)

Back

Authentication

X.509