Navigation

SCRAM-SHA-1

New in version 3.0.

SCRAM-SHA-1 is the default authentication mechanism for MongoDB. SCRAM-SHA-1 is an IETF standard, RFC 5802, that defines best practice methods for implementation of challenge-response mechanisms for authenticating users with passwords.

SCRAM-SHA-1 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.

SCRAM-SHA-1 Advantages

MongoDB’s implementation of SCRAM-SHA-1 represents an improvement in security over the previously-used MONGODB-CR, 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.

SCRAM-SHA-1 and MongoDB-CR User Credentials

SCRAM-SHA-1 is the default mechanism for MongoDB versions beginning with the 3.0 series. However, if you are upgrading a MongoDB 2.6 instances that already have users credentials, MongoDB will continue to use MONGODB-CR for challenge-response authentication until you upgrade the authentication schema.

Even when using the MONGODB-CR authentication mechanism, clients and drivers that support MongoDB 3.0 features (see Driver Compatibility Changes) will use the SCRAM communication protocol. That is, MONGODB-CR authentication mechanism also implies SCRAM-SHA-1.

For details on upgrading the authentication schema model to SCRAM-SHA-1, see Upgrade to SCRAM-SHA-1.

Warning

The procedure to upgrade to SCRAM-SHA-1 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

A driver upgrade is necessary to use the SCRAM-SHA-1 authentication mechanism if your current driver version does not support SCRAM-SHA-1.

The minimum driver versions that support SCRAM-SHA-1 are:

Driver Language Version
C 1.1.0
C++ 1.0.0
C# 1.10
Java 2.13
Node.js 1.4.29
Perl 0.708.0.0
PHP 1.6
Python 2.8
Motor 0.4
Ruby 1.12
Scala 2.8.0