Upgrade to SCRAM

Important

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

If you have user credentials stored in MONGODB-CR, you mustupgrade to Salted Challenge Response Authentication Mechanism(SCRAM)before you upgrade to version4.0.

The command listed in this procedure is only available in MongoDB3.0 through MongoDB 3.6.

Considerations

Backwards Incompatibility

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

The procedure also disables MONGODB-CR as an authenticationmechanism.

Requirements

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

Timing

Applicable only if you are upgrading from 2.6 to 3.0

• Once you upgrade the MongoDB binaries to version 3.0, allow yourMongoDB deployment to run for a day or two before following thisprocedure. This allows 3.0 some time to “burn in” and decreases thelikelihood of downgrades occurring after the user privilege modelupgrade. The user authentication and access control will continue towork as it did in 2.6.
• If you decide to upgrade the user authentication model immediatelyinstead of waiting the recommended “burn in” period, then for shardedclusters, you must wait at least 10 seconds after upgrading thesharded clusters to run the authentication upgrade command.

Replica Sets

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

Sharded Clusters

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

To override this behavior, run authSchemaUpgrade with theupgradeShards: false option. If you choose tooverride, you must run the upgrade procedure on the mongosfirst, and then run the procedure on the primary members ofeach shard.

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

Upgrade Drivers

Once upgraded, you must upgrade all drivers used by applications thatwill connect to upgraded database instances to version that supportSCRAM. The minimum driver versions that support SCRAM are:

See the MongoDB Drivers Page for links todownload upgraded drivers.

Prerequisites

Before upgrading the authentication model, your binaries must be atleast version 3.0.

For sharded clusters, ensure that all cluster components are atleast 3.0.

To upgrade, see upgrade MongoDB binaries to 3.0.

Upgrade 2.6 MONGODB-CR User Credentials to SCRAM User Credentials

Warning

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

The procedure also disables MONGODB-CR as an authenticationmechanism.

Important

To use SCRAM, a driver upgrade is necessary if your currentdriver version does not support SCRAM. See required driverversions for details.

Connect to the MongoDB instance.

Connect and authenticate to the mongod instance for asingle deployment, the primary mongod for a replica set, or amongos for a sharded cluster as an admin databaseuser with the role userAdminAnyDatabase.

Upgrade authentication schema.

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

Note

The command is available only in MongoDB versions 3.0 through 3.6.Refer to the specific version of the manual for details on on thecommand.

Run authSchemaUpgrade command.

db.adminCommand({authSchemaUpgrade: 1});

In case of error, you may safely rerun theauthSchemaUpgrade command.

Sharded cluster authSchemaUpgrade consideration.

For a sharded cluster withoutshard local users, authSchemaUpgrade will, bydefault, upgrade the authorization data of the shards as well,completing the upgrade.

You can, however, override this behavior by includingupgradeShards: false in the command, as in the followingexample:

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

If you override the default behavior or your cluster has shardlocal users, after running authSchemaUpgrade on amongos instance, you will need to connect to theprimary for each shard and repeat the upgrade process afterupgrading on the mongos.

Result

After this procedure is complete, all users in the database will haveSCRAM credentials, and any subsequently-created users will also havethis type of credentials.