Navigation

SCRAM

Note

Starting in version 4.0, MongoDB removes support for the deprecated MongoDB Challenge-Response (MONGODB-CR) authentication mechanism.

If your deployment has user credentials stored in MONGODB-CR schema, you must upgrade to SCRAM before you upgrade to version 4.0. For information on upgrading to SCRAM, see Upgrade to SCRAM.

Salted Challenge Response Authentication Mechanism (SCRAM) is the default authentication mechanism for MongoDB. SCRAM is based on the IETF RFC 5802 standard that defines best practices for implementation of challenge-response mechanisms for authenticating users with passwords.

Using SCRAM, MongoDB verifies the supplied user credentials against the user’s name, password and authentication database. The authentication database is the database where the user was created, and together with the user’s name, serves to identify the user.

Features

MongoDB’s implementation of SCRAM provides:

  • A tunable work factor (i.e. the iteration count),
  • Per-user random salts, and
  • Authentication of the server to the client as well as the client to the server.

SCRAM Mechanisms

MongoDB supports the following SCRAM mechanisms:

SCRAM Mechanism Description
SCRAM-SHA-1

Uses the SHA-1 hashing function.

To modify the iteration count for SCRAM-SHA-1, see scramIterationCount.

SCRAM-SHA-256

Uses the SHA-256 hashing function and requires featureCompatibilityVersion (fcv) set to 4.0.

To modify the iteration count for SCRAM-SHA-256, see scramSHA256IterationCount.

New in version 4.0.

When creating or updating a SCRAM user, you can indicate the specific SCRAM mechanism as well as indicate whether the server or the client digests the password. When using SCRAM-SHA-256, MongoDB requires server-side password hashing, i.e. the server digests the password. For details, see db.createUser() and db.updateUser().

Driver Support

To use SCRAM, you must upgrade your driver if your current driver version does not support SCRAM.

The minimum driver versions that support SCRAM are:

Driver Language Version Driver Language Version
C 1.1.0 Perl 1.0.0
C++ 1.0.0 PHP ext-mongo 1.6, ext-mongodb 1.0
C# 1.10 Python 2.8
Java 2.13 Motor 0.4
Node.js 1.4.29 Ruby 1.12
    Scala 2.8.0