Enforce Authentication in an Existing Sharded Cluster Without Downtime
On this page
The following procedure applies to sharded clusters using MongoDB 3.4 or later.
Earlier versions of MongoDB do not support no-downtime upgrade. For sharded clusters using earlier versions of MongoDB, see Enforce Keyfile Access Control in Sharded Cluster.
The following tutorial describes a procedure using
security.transitionToAuth to transition an existing sharded cluster to enforce authentication without incurring downtime.
Before you attempt this tutorial, please familiarize yourself with the contents of this document.
If you are using Cloud Manager or Ops Manager to manage your deployment, refer to Configure Access Control for MongoDB Deployments in the Cloud Manager manual or Ops Manager manual to enforce authentication.
Changed in version 3.6.
Starting with MongoDB 3.6, MongoDB binaries,
mongos, bind to
localhost by default. From MongoDB versions 2.6 to 3.4, only the binaries from the official MongoDB RPM (Red Hat, CentOS, Fedora Linux, and derivatives) and DEB (Debian, Ubuntu, and derivatives) packages would bind to
localhost by default. To learn more about this change, see Localhost Binding Compatibility Changes.
Refer to the Authentication documentation for a complete list of available client and internal authentication mechanisms.
This tutorial assumes that each shard replica set, as well as the config server replica set, can elect a new primary after stepping down its existing primary.
A replica set can elect a primary only if both of the following conditions are true:
With keyfile authentication, each
mongos instances in the sharded cluster uses the contents of the keyfile as the shared password for authenticating other members in the deployment. Only
mongos instances with the correct keyfile can join the sharded cluster.
The content of the keyfile must be between 6 and 1024 characters long and must be the same for all members of the sharded cluster.
On UNIX systems, the keyfile must not have group or world permissions. On Windows systems, keyfile permissions are not checked.
You can generate a keyfile using any method you choose. For example, the following operation uses
openssl to generate a complex pseudo-random 1024 character string to use for a keyfile. It then uses
chmod to change file permissions to provide read permissions for the file owner only:
For more information on using keyfiles for internal authentication, refer to Keyfiles.
You must connect to a
mongos to complete the steps in this section. The users created in these steps are cluster-level users and cannot be used for accessing individual shard replica sets.
db.createUser() method to create an administrator user and assign it the following roles:
Clients performing maintenance operations or user administrative operations on the sharded cluster must authenticate as this user at the completion of this tutorial. Create this user now to ensure that you have access to the cluster after enforcing authentication.
Passwords should be random, long, and complex to prevent or hinder malicious access.
In addition to the administrator user, you can create additional users before enforcing authentication.. This ensures access to the sharded cluster once you fully enforce authentication.
The following operation creates the user
joe on the
marketing database, assigning to this user the
readWrite role on the
Clients authenticating as
"joe" can perform read and write operations on the
See Database User Roles for roles provided by MongoDB.
While the sharded cluster does not currently enforce authentication, you can still update client applications to specify authentication credentials when connecting to the sharded cluster. This may prevent loss of connectivity at the completion of this tutorial.
Copy the existing
mongosconfiguration file, giving it a distinct name such as
.cfgif using Windows). You will use this new configuration file to transition the
mongosto enforce authentication in the sharded cluster. Retain the original configuration file for backup purposes.
To the new configuration file, add the following settings: