Docs4dev
Docs
mongodb / v3.6 / reference / release-notes-2.6-upgrade-authorization.html

Upgrade User Authorization Data to 2.6 Format

On this page

MongoDB 2.6 includes significant changes to the authorization model, which requires changes to the way that MongoDB stores users’ credentials. As a result, in addition to upgrading MongoDB processes, if your deployment uses authentication and authorization, after upgrading all MongoDB process to 2.6 you must also upgrade the authorization model.

Considerations

Complete all other Upgrade Requirements

Before upgrading the authorization model, you should first upgrade MongoDB binaries to 2.6. For sharded clusters, ensure that all cluster components are 2.6. If there are users in any database, be sure you have at least one user in the admin database with the role userAdminAnyDatabase before upgrading the MongoDB binaries.

Timing

Because downgrades are more difficult after you upgrade the user authorization model, once you upgrade the MongoDB binaries to version 2.6, allow your MongoDB deployment to run a day or two without upgrading the user authorization model.

This allows 2.6 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.4, but it will be impossible to create or modify users or to use user-defined roles until you run the authorization upgrade.

If you decide to upgrade the user authorization 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 authorization upgrade script.

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 a mongos and run the upgrade procedure to upgrade the cluster’s authorization data. By default, the procedure will upgrade the authorization data of the shards as well.

To override this behavior, run the upgrade command with the additional parameter upgradeShards: false. 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.

Requirements

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

Procedure

1

Connect to MongoDB instance.

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

2

Upgrade authorization 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, authSchemaUpgrade will upgrade the authorization data of the shards as well and the upgrade is complete. 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 behavior, 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

All users in a 2.6 system are stored in the admin.system.users collection. To manipulate these users, use the user management methods.

The upgrade procedure copies the version 2.4 admin.system.users collection to admin.system.backup_users.

The upgrade procedure leaves the version 2.4 <database>.system.users collection(s) intact.