Navigation

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.

To upgrade the authentication schema model to SCRAM, see Upgrade to SCRAM.

Warning

The procedure to upgrade to SCRAM discards the MONGODB-CR credentials used by 2.6. As such, the procedure is irreversible, short of restoring from backups.

The procedure also disables MONGODB-CR as an authentication mechanism.

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 1.6
Python 2.8
Motor 0.4
Ruby 1.12
Scala 2.8.0