Docs Menu
Docs Home
/
Languages
/
JavaScript
/
Node.js Driver
/
Security
/
Authentication

SCRAM Authentication Mechanisms

On this page

  • Overview
  • Code Placeholders
  • Default Authentication Mechanism
  • SCRAM-SHA-256
  • SCRAM-SHA-1
  • 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.

  • <cluster_url>: The network address of your MongoDB deployment.

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

Default Authentication Mechanism

The DEFAULT authentication mechanism is a fallback setting that instructs the driver to negotiate the first authentication mechanism supported by the server in the following order of preference:

  1. SCRAM-SHA-256

  2. SCRAM-SHA-1

  3. MONGODB-CR

If the DEFAULT option is specified, the driver first attempts to authenticate using SCRAM-SHA-256. If the version of the MongoDB instance does not support that mechanism, the driver attempts to authenticate using SCRAM-SHA-1. If the instance does not support that mechanism either, the driver attempts to authenticate using MONGODB-CR.

You can specify the default authentication mechanism by setting the authMechanism parameter to DEFAULT in the connection string, or by omitting the parameter since it is the default value.

The following example shows how to set the authentication mechanism to the default by setting authMechanism to DEFAULT in the connection string:

Important

Always URI encode the username and password using the encodeURIComponent method to ensure they are correctly parsed.

const { MongoClient } = require("mongodb");
// Replace the following with values for your environment.
const username = encodeURIComponent("<db_username>");
const password = encodeURIComponent("<db_password>");
const clusterUrl = "<cluster_url>";
const authMechanism = "DEFAULT";
// Replace the following with your MongoDB deployment's connection string.
const uri =
  `mongodb+srv://${username}:${password}@${clusterUrl}/?authMechanism=${authMechanism}`;
// Create a new MongoClient
const client = new MongoClient(uri);
// Function to connect to the server
async function run() {
  try {
    // Establish and verify connection
    await client.db("admin").command({ ping: 1 });
    console.log("Connected successfully to server");
  } finally {
    // Ensures that the client will close when you finish/error
    await client.close();
  }
}
run().catch(console.dir);

To learn more about the SCRAM version that MongoDB supports, see the SCRAM section of the MongoDB Server manual.

SCRAM-SHA-256

Note

SCRAM-SHA-256 is the default authentication method for MongoDB starting in version 4.0

SCRAM-SHA-256 is a SCRAM version that uses your username and password, encrypted with the SHA-256 algorithm to authenticate your user.

You can specify this authentication mechanism by setting the authMechanism to the value SCRAM-SHA-256 in the connection string as shown in the following sample code.

Important

Always URI encode the username and password using the encodeURIComponent method to ensure they are correctly parsed.

const { MongoClient } = require("mongodb");
// Replace the following with values for your environment.
const username = encodeURIComponent("<db_username>");
const password = encodeURIComponent("<db_password>");
const clusterUrl = "<cluster_url>";
const authMechanism = "SCRAM-SHA-256";
// Replace the following with your MongoDB deployment's connection string.
const uri =
  `mongodb+srv://${username}:${password}@${clusterUrl}/?authMechanism=${authMechanism}`;
// Create a new MongoClient
const client = new MongoClient(uri);
// Function to connect to the server
async function run() {
  try {
    // Establish and verify connection
    await client.db("admin").command({ ping: 1 });
    console.log("Connected successfully to server");
  } finally {
    // Ensures that the client will close when you finish/error
    await client.close();
  }
}
run().catch(console.dir);

SCRAM-SHA-1

Note

SCRAM-SHA-1 is the default authentication method for MongoDB versions 3.0, 3.2, 3.4, and 3.6.

SCRAM-SHA-1 is a SCRAM version that uses your username and password, encrypted with the SHA-1 algorithm to authenticate your user.

You can specify this authentication mechanism by setting the authMechanism parameter to the value SCRAM-SHA-1 in the connection string as shown in the following sample code.

Important

Always URI encode the username and password using the encodeURIComponent method to ensure they are correctly parsed.

const { MongoClient } = require("mongodb");
// Replace the following with values for your environment.
const username = encodeURIComponent("<db_username>");
const password = encodeURIComponent("<db_password>");
const clusterUrl = "<cluster_url>";
const authMechanism = "SCRAM-SHA-1";
// Replace the following with your MongoDB deployment's connection string.
const uri =
  `mongodb+srv://${username}:${password}@${clusterUrl}/?authMechanism=${authMechanism}`;
// Create a new MongoClient
const client = new MongoClient(uri);
// Function to connect to the server
async function run() {
  try {
    // Establish and verify connection
    await client.db("admin").command({ ping: 1 });
    console.log("Connected successfully to server");
  } finally {
    // Ensures that the client will close when you finish/error
    await client.close();
  }
}
run().catch(console.dir);

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