Navigation
This version of the documentation is archived and no longer supported.

SCRAM

New in version 3.0.

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.

MongoDB’s implementation of SCRAM uses the SHA-1 hashing function.

SCRAM Advantages

MongoDB’s implementation of SCRAM represents an improvement in security over the MongoDB challenge response authentication mechanism, providing:

  • A tunable work factor (iterationCount),
  • Per-user random salts rather than server-wide salts,
  • A cryptographically stronger hash function (SHA-1 rather than MD5), and
  • Authentication of the server to the client as well as the client to the server.

MongoDB-CR User Credentials and SCRAM

After you upgrade a deployment that already has MongoDB Challenge and Response (MONGODB-CR) user credentials, if you have not upgraded the authentication schema, you can continue to use MONGODB-CR:

  • For older versions of drivers that do not support MongoDB 3.0+ features, you will continue to use MONGODB-CR.
  • For drivers that support MongoDB 3.0+ features (see Driver Compatibility Changes), you can explicitly specify MONGODB-CR as the authentication mechanism to use MONGODB-CR. Otherwise, the credentials are temporarily converted to use SCRAM during authentication to provide improved protection from passive eavesdroppers; this temporary conversion does not affect how the credentials are stored.

Note

As of MongoDB 3.6, MONGODB-CR authentication mechanism is deprecated. If you have not upgraded your MONGODB-CR authentication schema to SCRAM, see Upgrade to SCRAM.

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
C 1.1.0
C++ 1.0.0
C# 1.10
Java 2.13
Node.js 1.4.29
Perl 1.0.0
PHP ext-mongo 1.6, ext-mongodb 1.0
Python 2.8
Motor 0.4
Ruby 1.12
Scala 2.8.0