Upgrade to SCRAM
On this page
Important
Starting in version 4.0, MongoDB removes support for the deprecated
MongoDB Challenge-Response (MONGODB-CR) authentication mechanism.
If you have user credentials stored in MONGODB-CR, you must
upgrade to Salted Challenge Response Authentication Mechanism
(SCRAM) before you upgrade to version
4.0.
The command listed in this procedure is only available in MongoDB 3.0 through MongoDB 3.6.
Considerations
Backwards Incompatibility
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.
Requirements
To upgrade the authentication model, you must have a user in the
admin 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 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 Drivers
Once upgraded, you must upgrade all drivers used by applications that will connect to upgraded database instances to version that support SCRAM. The minimum driver versions that support SCRAM are:
Driver Language | Version | Driver Language | Version |
|---|---|---|---|
See the MongoDB Drivers Page for links to download upgraded drivers.
Prerequisites
Before upgrading the authentication model, your binaries must be at least version 3.0.
For sharded clusters, ensure that all cluster components are at least 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-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 SCRAM, a driver upgrade is necessary if your current driver version does not support SCRAM. See required driver versions for details.
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.
Upgrade authentication schema.
Use the authSchemaUpgrade command in the admin
database 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 the command.
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 credentials, and any subsequently-created users will also have this type of credentials.