Upgrade to `SCRAM-SHA-1`¶

On this page

Overview¶

MongoDB 3.0 includes support for the SCRAM-SHA-1 challenge-response user authentication mechanism, which changes how MongoDB uses and stores user credentials.

For deployments that already contain user authentication data, to use the SCRAM-SHA-1 mechanism, you must upgrade the authentication schema in addition to upgrading the MongoDB processes.

You may, alternatively, opt to continue to use the MONGODB-CR challenge-response mechanism and skip this upgrade.

See Upgrade Scenarios for details.

Upgrade Scenarios¶

The following scenarios are possible when upgrading from 2.6 to 3.0:

Continue to Use `MONGODB-CR`¶

If you are upgrading from a 2.6 database with existing user authentication data, to continue to use MONGODB-CR for existing challenge-response users, no upgrade to the existing user data is required. However, new challenge-response users created in 3.0 will use the following authentication mechanism:

If you populated MongoDB 3.0 user data by importing the 2.6 user authentication data, including user data, new challenge-response users created in MongoDB 3.0 will use SCRAM-SHA1.
If you run MongoDB 3.0 binary against the 2.6 data files, including the user authentication data files, new challenge-response users created in MongoDB 3.0 will continue to use the MONGODB-CR.

You can execute the upgrade to SCRAM-SHA-1 at any point in the future.

Use `SCRAM-SHA-1`¶

If you are starting with a new 3.0 installation without any users or upgrading from a 2.6 database that has no users, to use SCRAM-SHA-1, no user data upgrade is required. All newly created users will have the correct format for SCRAM-SHA-1.
If you are upgrading from a 2.6 database with existing user data, to use SCRAM-SHA-1, follow the steps in Upgrade 2.6 MONGODB-CR Users to SCRAM-SHA-1.

Important

Before you attempt any upgrade, familiarize yourself with the Considerations as the upgrade to SCRAM-SHA-1 is irreversible short of restoring from backups.

Recommendation¶

SCRAM-SHA-1 represents a significant improvement in security over MONGODB-CR, the previous default authentication mechanism: you are strongly urged to upgrade. For advantages of using SCRAM-SHA-1, see SCRAM-SHA-1.

Considerations¶

Backwards Incompatibility¶

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.

Upgrade Binaries¶

Before upgrading the authentication model, you should first upgrade MongoDB binaries to 3.0. For sharded clusters, ensure that all cluster components are 3.0.

Upgrade Drivers¶

You must upgrade all drivers used by applications that will connect to upgraded database instances to version that 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

See the MongoDB Drivers Page for links to download upgraded drivers.

Requirements¶

To upgrade the authentication model, you must have a user in the admin database with the role userAdminAnyDatabase.

Timing¶

Because downgrades are more difficult after you upgrade the user authentication model, once you upgrade the MongoDB binaries to version 3.0, allow your MongoDB deployment to run for a day or two before following this procedure.

This allows 3.0 some time to “burn in” and decreases the likelihood of downgrades occurring after the user privilege model upgrade. The user authentication and access control will continue to work as it did in 2.6.

If you decide to upgrade the user authentication model immediately instead of waiting the recommended “burn in” period, then for sharded clusters, you must wait at least 10 seconds after upgrading the sharded clusters to run the authentication upgrade command.

Replica Sets¶

For a replica set, it is only necessary to run the upgrade process on the primary as the changes will automatically replicate to the secondaries.

Sharded Clusters¶

For a sharded cluster, connect to one mongos instance and run the upgrade procedure to upgrade the cluster’s authentication data. By default, the procedure will upgrade the authentication data of the shards as well.

To override this behavior, run authSchemaUpgrade with the upgradeShards: false option. If you choose to override, you must run the upgrade procedure on the mongos first, and then run the procedure on the primary members of each shard.

For a sharded cluster, do not run the upgrade process directly against the config servers. Instead, perform the upgrade process using one mongos instance to interact with the config database.

Upgrade 2.6 `MONGODB-CR` Users 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.

Important

To use the SCRAM-SHA-1 authentication mechanism, a driver upgrade is necessary if your current driver version does not support SCRAM-SHA-1. See required driver versions for details.

1

Connect to the MongoDB instance.¶

Connect and authenticate to the mongod instance for a single deployment, the primary mongod for a replica set, or a mongos for a sharded cluster as an admin database user with the role userAdminAnyDatabase.

2

Upgrade authentication schema.¶

Use the authSchemaUpgrade command in the admin database to update the user data using the mongo shell.

Run `authSchemaUpgrade` command.¶

db.adminCommand({authSchemaUpgrade: 1});

In case of error, you may safely rerun the authSchemaUpgrade command.

Sharded cluster `authSchemaUpgrade` consideration.¶

For a sharded cluster without shard local users, authSchemaUpgrade will, by default, upgrade the authorization data of the shards as well, completing the upgrade.

You can, however, override this behavior by including upgradeShards: false in the command, as in the following example:

db.adminCommand(
   {authSchemaUpgrade: 1, upgradeShards: false }
);

If you override the default behavior or your cluster has shard local users, after running authSchemaUpgrade on a mongos instance, you will need to connect to the primary for each shard and repeat the upgrade process after upgrading on the mongos.

Result¶

After this procedure is complete, all users in the database will have SCRAM-SHA-1-style credentials, and any subsequently-created users will also have this type of credentials.

Additional Resources¶

← Upgrade MongoDB to 3.0 Downgrade MongoDB from 3.0 →

Upgrade to SCRAM-SHA-1¶