Docs Menu
Docs Home
/
Languages
/
Java
/
Java Sync Driver
/
Security
/
Authentication

SCRAM

On this page

  • Overview
  • Code Placeholders
  • Specify the Default SCRAM Authentication Mechanism
  • Specify SCRAM-SHA-256 Authentication
  • Specify SCRAM-SHA-1 Authentication
  • API Documentation

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 instead, 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.

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 don't 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.

Specify the Default SCRAM Authentication Mechanism

To use the default SCRAM mechanism to authenticate your MongoDB user, specify your MongoDB credentials, but don't specify an authentication mechanism. Select the Connection String or the MongoCredential tab below for instructions and sample code for the corresponding syntax:

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

MongoClient mongoClient = MongoClients.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. The code to instantiate a MongoClient resembles the following:

MongoCredential credential = MongoCredential.createCredential("<db_username>", "<authenticationDb>", "<db_password>");
MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
                builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
        .credential(credential)
        .build());

For more information about the challenge-response (CR) and salted challenge-response authentication mechanisms (SCRAM) that MongoDB supports, see the SCRAM section of the MongoDB Server manual.

Specify SCRAM-SHA-256 Authentication

SCRAM-SHA-256 is the default authentication method for MongoDB starting in MongoDB 4.0, but this code example shows how to explicitly use this mechanism. Select the Connection String or the MongoCredential tab 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. The code to instantiate a MongoClient resembles the following:

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

To specify the SCRAM-SHA-256 authentication mechanism by using the MongoCredential class, use the createScramSha256Credential() method. The code to instantiate a MongoClient resembles the following:

MongoCredential credential = MongoCredential.createScramSha256Credential("<db_username>", "<authenticationDb>", "<db_password>");
MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
                builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
        .credential(credential)
        .build());

Specify SCRAM-SHA-1 Authentication

SCRAM-SHA-1 is the default authentication method for MongoDB versions earlier than 4.0, but this code example shows how to explicitly use this mechanism. Select the Connection String or the MongoCredential tab for instructions and sample code for specifying this 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. The code to instantiate a MongoClient resembles the following:

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

To specify the SCRAM-SHA-1 authentication mechanism by using the MongoCredential class, use the createScramSha1Credential() method. The code to instantiate a MongoClient resembles the following:

MongoCredential credential = MongoCredential.createScramSha1Credential("<db_username>", "<authenticationDb>", "<db_password>");
MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
                builder.hosts(Arrays.asList(new ServerAddress("<hostname>", <port>))))
        .credential(credential)
        .build());

API Documentation

To learn more about any of the methods or types discussed on this page, see the following API documentation:

Back

Authentication

Next

X.509