Docs Menu
Docs Home
/
Languages
/
Python
/
PyMongo
/
Security
/
Authentication

SCRAM

On this page

  • Overview
  • Code Placeholders
  • Using SCRAM Authentication in Your Application
  • 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:

  • +srv: Include this option in your connection string prefix only if you are connecting to a MongoDB Atlas cluster. To learn more about the +srv option, see Connection String Formats in the MongoDB Server manual.

  • <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.

  • <authenticationMechanism>: Set to SCRAM-SHA-1 or SCRAM-SHA-256.

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

Important

Percent-Encoding

You must percent-encode a username and password before you include them in a MongoDB URI. The quote_plus() method, available in the urllib.parse module, is one way to perform this task. For example, calling quote_plus("and / or") returns the string and+%2F+or.

Don't percent-encode the username or password when passing them as arguments to MongoClient.

Using SCRAM Authentication in Your Application

To use SCRAM to authenticate, set the authMechanism connection option to SCRAM-SHA-1 or SCRAM-SHA-256. You can set this option in two ways: by passing an argument to the MongoClient constructor or through a parameter in your connection string.

client = pymongo.MongoClient("mongodb[+srv]://<hostname>:<port>",
                             username="<db_username>",
                             password="<db_password>",
                             authSource="<authenticationDb>",
                             authMechanism="<authenticationMechanism>")
uri = ("mongodb[+srv]://<percent-encoded db_username>:<percent-encoded db_password>"
       "@<hostname>:<port>/?"
       "authSource=<authenticationDb>"
       "&authMechanism=<authenticationMechanism>")
client = pymongo.MongoClient(uri)

API Documentation

To learn more about authenticating your application in PyMongo, see the following API documentation:

Back

Authentication

Next

X.509