- Release Notes >
- Release Notes for MongoDB 3.0 >
- Upgrade to SCRAM
Upgrade to SCRAM¶
On this page
Overview¶
Starting in version 3.0, MongoDB includes support for the Salted Challenge Response Authentication Mechanism (SCRAM), which changes how MongoDB uses and stores user credentials.
If you are starting with a new 3.0+ deployment without any users or upgrading from a 2.6 database that has no users, no authentication schema upgrade to SCRAM is required. All newly created users will have the correct format for SCRAM.
For 3.0+ deployments with existing MongoDB Challenge and Response (MONGODB-CR) user data model, the following procedure upgrades the authentication schema to SCRAM.
Recommendation
SCRAM represents a significant improvement in security over MongoDB Challenge and Response (MONGODB-CR), the previous default authentication mechanism: you are strongly urged to upgrade from the MONGODB-CR authentication schema to SCRAM. For advantages of using SCRAM over MONGODB-CR, see SCRAM Advantages.
Existing 2.6 User Credentials¶
The following information details the authentication mechanism used for MongoDB 3.0+ deployments that contains MONGODB-CR user credentials; that is, before upgrading the authentication schema.
If you upgraded from version 2.6 with existing user authentication data to MongoDB 3.0 (or run MongoDB 3.0 binary against the 2.6 data files):
MongoDB Users | Credentials Stored in 3.0 | Behavior |
---|---|---|
Existing challenge-response users | MONGODB-CR credentials | 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), the default behavior is to
temporarily convert the credentials to SCRAM during authentication;
this temporary conversion does not affect how the credentials are
stored. If you choose to use |
New challenge-response users | MONGODB-CR credentials | 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), the default behavior is to
temporarily convert the credentials to SCRAM during authentication;
this temporary conversion does not affect how the credentials are
stored. If you choose to use |
If you populated MongoDB 3.0 user data by importing the 2.6 user authentication data:
MongoDB Users | Credentials Stored in 3.0 | Behavior |
---|---|---|
Existing challenge-response users | MONGODB-CR credentials | 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), the default behavior is to
temporarily convert the credentials to SCRAM during authentication;
this temporary conversion does not affect how the credentials are
stored. If you choose to use |
New challenge-response users | SCRAM credentials | Requires drivers that support MongoDB 3.0+ features (see Driver Compatibility Changes). Can only use SCRAM. |
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¶
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 Drivers¶
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 |
---|---|
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 |
See the MongoDB Drivers Page for links to download upgraded drivers.
Prerequisites¶
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 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.
Run authSchemaUpgrade
command.¶
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:
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.