Update Replica Set to Keyfile Authentication¶

Create a keyfile.¶

With keyfile authentication, each mongod instances in the replica set uses the contents of the keyfile as the shared password for authenticating other members in the deployment. Only mongod instances with the correct keyfile can join the replica set.

A key’s length must be between 6 and 1024 characters and may only contain characters in the base64 set. All members of the replica set must share at least one common key.

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 as a shared password. 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.

Copy the keyfile to each replica set member.¶

Copy the keyfile to each server hosting the replica set members. Ensure that the user running the mongod 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 instances, such as a USB drive or a network attached storage device.

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.¶

Restart each mongod in the replica set with either the security.keyFile configuration file setting or the --keyFile command-line option. Running mongod with the --keyFile command-line option or the security.keyFile configuration file setting enforces both Internal/Membership Authentication and Role-Based Access Control.

security:
  keyFile: <path-to-keyfile>
replication:
  replSetName: <replicaSetName>
net:
   bindIp: localhost,<hostname(s)|ip address(es)>

mongod --config <path-to-config-file>

mongod --keyFile <path-to-keyfile> --replSet <replicaSetName> --bind_ip localhost,<hostname(s)|ip address(es)>

Connect to the primary using the localhost interface.¶

Connect a mongo shell to one of the mongod instances over the localhost interface. You must run the mongo shell on the same physical machine as the mongod instance.

Use rs.status() to identify the primary replica set member. If you are connected to the primary, continue to the next step. If not, connect a mongo shell to the primary over the localhost interface.

Create the user administrator.¶

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.

admin = db.getSiblingDB("admin")
admin.createUser(
  {
    user: "fred",
    pwd: passwordPrompt(), // or cleartext password
    roles: [ { role: "userAdminAnyDatabase", db: "admin" } ]
  }
)

Enter the password when prompted. 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", passwordPrompt()) // or cleartext password

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  --authenticationDatabase "admin"

If you do not specify the password to the -p command-line option, the mongo shell prompts for the password.

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" : passwordPrompt(),     // or cleartext password
    roles: [ { "role" : "clusterAdmin", "db" : "admin" } ]
  }
)

Enter the password when prompted.

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.