How to Migrate MONGODB-CR to SCRAM-SHA-1
Introduction
This tutorial will explain how to perform MongoDB authentication, perform migration of MONGODB-CR to SCRAM-SHA-1 and explain the MONGODB-CR and SCRAM-SHA-1 authentication mechanisms. Know that the release of MongoDB version 3.0 has effectively replaced MONGODB-CR with SCRAM-SHA-1. As a result of this release, MONGODB-CR has now been deprecated. Users are strongly encouraged to upgrade to a version of MongoDB that supports SCRAM-SHA-1.
Prerequisite
- A basic working knowledge of the MongoDB authentication mechanism.
The SCRAM-SHA-1 Authentication Mechanism
SCRAM-SHA-1 (Salted Challenge Response Authentication Mechanism – Secure Hash Algorithm 1) is one of the mechanisms responsible for authenticating a client or user into MongoDB. SCRAM-SHA-1 is an IETFS — Internet Engineering Task Force Standard that defines the best practices and methods for the enforcement of the challenge and response mechanism for authenticating users with passwords.
The MONGODB-CR Authentication Mechanism
MONGODB-CR is one of the MongoDB supported authentication mechanism, falling under the challenge and response and username and password authentication mechanisms.
Migrating from MONGODB-CR to SCRAM-SHA-1
There are two main reasons for users to migrate from the MONGODB-CR to the SCRAM-SHA-1 authentication mechanism:
When the older version of MongoDB 2.x was upgraded to version 3.x, by the replacement of the
mongodbinary, then all users had to useMONGODDB-CRuntil the schema was upgraded.When data is imported from older systems into a newer version of MongoDB, meaning 3.X and above, all current users must then use
MONGODB-CRwhereas all new users must useSCRAM-SHA-1.
Considerations
Before proceeding with the migration process there are a few noteworthy considerations.
Backwards incompatibility
When upgrading from MONGODB-CR 2.6 version system to SCRAM-SHA-1, the credentials in the older version will be permanetly discarded and the procedure will be irreversible.
Upgrade Binaries
The MongoDB binaries must be upgraded to 3.X prior to upgrading the authentication model. This will ensure all clusters of the sharded clusters components were in a 3.X version.
Upgrade Drivers
All drivers used by applications that will connect the upgraded database instances to version that support SCRAM-SHA-1 must also be upgraded. In other words, all drivers that any applications are using to connect to the upgraded database instances, in order to support SCRAM-SHA-1, must be upgrade or the system will not function.
The Simple Migration Command
Provided there is now a clear understanding of what the SCRAM-SHA-1 authentication mechanism is and why is should be applied to upgrade this authentication model, migrate the users of a 2.6 system to 3.X version that will use SCRAM-SHA-1.
Begin by executing the .find() command for all the users to retrieve their credentials. The results should resemble the following:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | { "_id" : "admin.user1", "user" : "user1", "db" : "admin", "credentials" : { "MONGODB-CR" : "945fd4fb6b7f3749888ea9251a89c592" }, "roles" : [ { "role" : "root", "db" : "admin" } ] } |
The above results show that only one user, “user1,” still uses the MONGODB-CR. Execute the following command to migrate the user into SCRAM-SHA-1:
1 | db.adminCommand({authSchemaUpgrade: 1}) |
The results will show a confirmation similar to the following:
1 | {"done" : true, "ok" : 1} |
Verify the migration was successful by using the .find() command again. The result should resemble the following:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | > db.system.users.find().pretty(); { "_id" : "admin.user1", "userId" : UUID("d45d4fb6-b7f3-4749-888e-a9251a89c592"), "user" : "user1", "db" : "admin", "credentials" : { "SCRAM-SHA-1" : { "iterationCount" : 10000, "salt" : "mw+OhsQyade4FI5LMlweWg==", "storedKey" : "cwsxp8LZEpcmRS9mHV33pNkkX2I=", "serverKey" : "RZZAzftEBlUONMgJ3Ymjk85IIPc=" }, "roles" : [ { "role" : "root", "db" : "admin" } ] } |
The above result show the users is no longer using the MONGODB-CR, but is now using SCRAM-SHA-1. As a result, MongoDB has completely disabled MONGODB-CR on this database and will no longer be able to authenticate users that uses MONGODB-CR in this database.
Conclusion
In this tutorial has explained what the MONGODB-CR and SCRAM-SHA-1 authentication mechanism are, how to perform MongoDB authentication and execute the migration of MONGODB-CR to SCRAM-SHA-1. Remember that the MongoDB binaries must be upgraded to 3.X prior to upgrading the authentication model and that all drivers used to connect the upgraded database to a version that supports SCRAM-SHA-1 must also be upgraded. Bear in mind that performing the migration of MONGODB-CR to SCRAM-SHA-1 is a permanent action, and it cannot be undone. This is often a very distractive process, therefore extreme caution must be taken when executing the process as the former MONGODB-CR credentials cannot be reverted back to.
Pilot the ObjectRocket Platform Free!
Try Fully-Managed CockroachDB, Elasticsearch, MongoDB, PostgreSQL (Beta) or Redis.
Get Started