Enforce Keyfile Access Control in Sharded Cluster
On this page
Overview
Enforcing access control on a sharded cluster requires configuring:
- Security between components of the cluster using Internal Authentication.
- Security between connecting clients and the cluster using Role-Based Access Control.
For this tutorial, each member of the sharded cluster must use the same internal authentication mechanism and settings. This means enforcing internal authentication on each mongos and mongod in the cluster.
The following tutorial uses a keyfile to enable internal authentication.
Enforcing internal authentication also enforces user access control. To connect to the replica set, clients like the mongo shell need to use a user account. See Access Control.
CloudManager and OpsManager
If Cloud Manager or Ops Manager is managing your deployment, internal authentication is automatically enforced.
To configure Access Control on a managed deployment, see: Configure Access Control for MongoDB Deployments in the Cloud Manager manual or in the Ops Manager manual .
Considerations
IP Binding
Changed in version 3.6.
Starting with MongoDB 3.6, MongoDB binaries, mongod and 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.
Operating System
This tutorial primarily refers to the mongod process. Windows users should use the mongod.exe program instead.
Keyfile Security
Keyfiles are bare-minimum forms of security and are best suited for testing or development environments. For production environments we recommend using x.509 certificates.
Access Control
This tutorial covers creating the minimum number of administrative users on the admin database only. For the user authentication, the tutorial uses the default SCRAM authentication mechanism. Challenge-response security mechanisms are best suited for testing or development environments. For production environments, we recommend using x.509 certificates or LDAP Proxy Authentication (available for MongoDB Enterprise only) or Kerberos Authentication (available for MongoDB Enterprise only).
For details on creating users for specific authentication mechanism, refer to the specific authentication mechanism pages.
See ➤ Configure Role-Based Access Control for best practices for user creation and management.
Users
In general, to create users for a sharded clusters, connect to the mongos and add the sharded cluster users.
However, some maintenance operations require direct connections to specific shards in a sharded cluster. To perform these operations, you must connect directly to the shard and authenticate as a shard-local administrative user.
Shard-local users exist only in the specific shard and should only be used for shard-specific maintenance and configuration. You cannot connect to the mongos with shard-local users.
See the Users security documentation for more information.
Procedures
Enforce Keyfile Internal Authentication on Existing Sharded Cluster Deployment
1
Create a keyfile.
With keyfile authentication, each mongod or mongos instances in the sharded cluster uses the contents of the keyfile as the shared password for authenticating other members in the deployment. Only mongod or 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.
Note
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:
openssl rand -base64 756 > <path-to-keyfile>
chmod 400 <path-to-keyfile>
See Keyfiles for additional details and requirements for using keyfiles.
2
Copy the keyfile to each component in the sharded cluster.
Every server hosting a mongod or mongos component of the sharded cluster must contain a copy of the keyfile.
Copy the keyfile to each server hosting the sharded cluster members. Ensure that the user running the mongod or mongos instances is the owner of the file and can access the keyfile.
Avoid storing the keyfile on storage mediums that can be easily disconnected from the hardware hosting the mongod or mongos instances, such as a USB drive or a network attached storage device.
3
Disable the Balancer.
Connect a mongo shell to a mongos.
sh.stopBalancer()
The balancer may not stop immediately if a migration is in progress. The sh.stopBalancer() method blocks the shell until the balancer stops.
Use sh.getBalancerState() to verify that the balancer has stopped.
sh.getBalancerState()
Important
Do not proceed until the balancer has stopped running.
See Manage Sharded Cluster Balancer for tutorials on configuring sharded cluster balancer behavior.
4
Shut down all mongos instances for the sharded cluster.
Connect a mongo shell to each mongos and shut them down.
Use the db.shutdownServer() method on the admin database to safely shut down the mongos:
db.getSiblingDB("admin").shutdownServer()
Repeat until all mongos instances in the cluster are offline.
Once this step is complete, all mongos instances in the cluster should be offline.
5
Shut down config server mongod instances.
Connect a mongo shell to each mongod in the config server deployment and shut them down.
For replica set config server deployments, shut down the primary member last.
Use the db.shutdownServer() method on the admin database to safely shut down the mongod:
db.getSiblingDB("admin").shutdownServer()
Repeat until all config servers are offline.
6
Shut down shard replica set mongod instances.
For each shard replica set, connect a mongo shell to each mongod member in the replica set and shut them down. Shut down the primary member last.
Use the db.shutdownServer() method on the admin database to safely shut down the mongod:
db.getSiblingDB("admin").shutdownServer()