- Security >
- Authentication >
- Internal Authentication >
- Enforce Keyfile Access Control in a Replica Set
Enforce Keyfile Access Control in a Replica Set¶
On this page
Overview¶
Enforcing access control on a replica set requires configuring:
- Security between members of the replica set using Internal Authentication, and
- Security between connecting clients and the replica set using User Access Controls.
For this tutorial, each member of the replica set uses the same internal authentication mechanism and settings.
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.
Cloud Manager and Ops Manager¶
If Cloud Manager or Ops Manager is managing your deployment, see: Configure Access Control for MongoDB Deployments in the Cloud Manager manual or in the Ops Manager manual for enforcing access control.
Considerations¶
Operating System¶
This tutorial uses the mongod programs. 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-SHA-1 authentication mechanism. Challenge-response security mechanisms are are best suited for testing or development environments. For production environments, we recommend using x.509 certificates or LDAP Proxy Authority 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.
Downtime¶
Enforcing access control on an existing replica set requires downtime.
Enforce Keyfile Access Control on Existing Replica Set¶
Create a keyfile.¶
The contents of the keyfile serves as the shared password for the members of the replica set. The content of the keyfile must be the same for all members of the replica set.
You can generate a keyfile using any method you choose. The contents of the keyfile must be between 6 and 1024 characters long.
Note
On UNIX systems, the keyfile must not have group or world permissions. On Windows systems, keyfile permissions are not checked.
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 755 > <path-to-keyfile>
chmod 400 <path-to-keyfile>
See Keyfiles for additional details and requirements for using keyfiles.
Copy the keyfile to each replica set member.¶
Copy the keyfile to each server hosting the replica set members. Use a consistent location for each server.
Important
Do not use shared network locations or storage mediums such as USB drives for storing the keyfile.
Ensure that the user running the mongod instances can access the keyfile.
Shut down all members of the replica set.¶
Shut down each mongod in the replica set, starting with the secondaries. Continue until all members of the replica set are offline, including any arbiters. The primary must be the last member shut down to avoid potential rollbacks.
To shut down a mongod, connect each mongod using a mongo shell and issue the db.shutdownServer() on the admin database:
use admin
db.shutdownServer()
At the end of this step, all members of the replica set should be offline.
Restart each member of the replica set with access control enforced.¶
Running a mongod with the keyFile parameter enforces both Internal Authentication and Role-Based Access Control.
Start each mongod in the replica set using either a configuration file or the command line.
Use the original replica set name for replSetName when starting each member. You cannot change the name of a replica set, and attempting to do so results in errors.
Configuration File
If using a configuration file, set the security.keyFile option to the keyfile’s path, and the replication.replSetName option to the replica set name:
security:
keyFile: <path-to-keyfile>
replication:
replSetName: <replicaSetName>
Start the mongod using the configuration file:
mongod --config <path-to-config-file>
For more information on the configuration file, see configuration options.
Command Line
If using the command line option, start the mongod with the --keyFile and --replSet parameters:
mongod --keyFile <path-to-keyfile> --replSet <replicaSetName>
For more information on startup parameters, see the mongod reference page.
Include additional settings as appropriate to your deployment.
Connect to a member of the replica set over the localhost interface.¶
Connect a mongo shell to one of the config server mongod instances over the localhost interface. You must run the mongo shell on the same physical machine as the mongod instance.
The localhost interface is only available since no users have been created for the deployment. The localhost interface closes after the creation of the first user.
Create the user administrator.¶
Important
After you create the first user, the localhost exception is no longer available.
The first user must have privileges to create other users, such as a user with the userAdminAnyDatabase. This ensures that you can create additional users after the Localhost Exception closes.
If at least one user does not have privileges to create users, once the localhost exception closes you may be unable to create or modify users with new privileges, and therefore unable to access necessary operations.
Add a user using the db.createUser() method. The user should have at minimum the userAdminAnyDatabase role on the admin database.
You must be connected to the primary to create users.
The following example creates the user fred with the userAdminAnyDatabase role on the admin database.
Important
Passwords should be random, long, and complex to ensure system security and to prevent or delay malicious access.
admin = db.getSiblingDB("admin")
admin.createUser(
{
user: "fred",
pwd: "changeme1",
roles: [ { role: "userAdminAnyDatabase", db: "admin" } ]
}
)
See Database User Roles for a full list of built-in roles and related to database administration operations.
Authenticate as the User Administrator.¶
Authenticate to the admin database.
In the mongo shell, use db.auth() to authenticate. For example, the following authenticate as the user administrator fred:
db.getSiblingDB("admin").auth("fred", "changeme1" )
Alternatively, connect a new mongo shell to the primary replica set member using the -u <username>, -p <password>, and the --authenticationDatabase parameters.
mongo -u "fred" -p "changeme1" --authenticationDatabase "admin"
Create the cluster administrator (Optional).¶
The cluster administrator user has the clusterAdmin role, which grants access to replication operations.
Create a cluster administrator user and assign the clusterAdmin role in the admin database:
db.getSiblingDB("admin").createUser(
{
"user" : "ravi",
"pwd" : "changeme2",
roles: [ { "role" : "clusterAdmin", "db" : "admin" } ]
}
)
See Cluster Administration Roles for a full list of built-in roles related to replica set operations.
Create additional users (Optional).¶
Create users to allow clients to connect and interact with the replica set. See Database User Roles for basic built-in roles to use in creating read-only and read-write users.
You may also want additional administrative users. For more information on users, see Users.
x.509 Internal Authentication¶
For details on using x.509 for internal authentication, see Use x.509 Certificate for Membership Authentication.
To upgrade from keyfile internal authentication to x.509 internal authentication, see Upgrade from Keyfile Authentication to x.509 Authentication.