Update Replica Set to Keyfile Authentication¶

On this page

Overview
Considerations
Enforce Keyfile Access Control on Existing Replica Set
x.509 Internal Authentication

Overview¶

Enforcing access control on an existing 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 Users.

Cloud Manager and Ops Manager¶

If Cloud Manager or Ops Manager is managing your deployment, see the Cloud Manager manual or the Ops Manager manual for enforcing access control.

Considerations¶

Tip

When possible, use a logical DNS hostname instead of an ip address, particularly when configuring replica set members or sharded cluster members. The use of logical DNS hostnames avoids configuration changes due to ip address changes.

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

Users¶

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.

Downtime¶

The following procedure for enforcing access control requires downtime. For a procedure that does not require downtime, see Update Replica Set to Keyfile Authentication (No Downtime) instead.

Enforce Keyfile Access Control on Existing Replica Set¶

1

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.

Note

Starting in MongoDB 4.2, keyfiles for internal membership authentication use YAML format to allow for multiple keys in a keyfile. The YAML format accepts content of:

a single key string (same as in earlier versions),
multiple key strings (each string must be enclosed in quotes), or
sequence of key strings.

The YAML format is compatible with the existing single-key keyfiles that use the text file format.

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.

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 as a shared password. It then uses chmod to change file permissions to provide read permissions for the file owner only:

copy

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

3

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:

copy

use admin
db.shutdownServer()

At the end of this step, all members of the replica set should be offline.

4

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.

Configuration File¶

If using a configuration file, set

security.keyFile to the keyfile’s path, and
replication.replSetName to the replica set name.

Include additional options as required for your configuration. For instance, if you wish remote clients to connect to your deployment or your deployment members are run on different hosts, specify the net.bindIp setting. For more information, see Localhost Binding Compatibility Changes.

copy

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

Start the mongod using the configuration file:

copy

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

For more information on the configuration file, see configuration options.

Command Line¶

If using the command line options, start the mongod with the following options:

--keyFile set to the keyfile’s path, and
--replSet set to the replica set name.

Include additional options as required for your configuration. For instance, if you wish remote clients to connect to your deployment or your deployment members are run on different hosts, specify the --bind_ip. For more information, see Localhost Binding Compatibility Changes.

copy

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

Tip

When possible, use a logical DNS hostname instead of an ip address, particularly when configuring replica set members or sharded cluster members. The use of logical DNS hostnames avoids configuration changes due to ip address changes.

For more information on command-line options, see the mongod reference page.

5

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.

Important

You must connect to the primary before proceeding.

6

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.

Tip

Starting in version 4.2 of the mongo shell, you can use the passwordPrompt() method in conjunction with various user authentication/management methods/commands to prompt for the password instead of specifying the password directly in the method/command call. However, you can still specify the password directly as you would with earlier versions of the mongo shell.

copy

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.

7

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:

Tip

Starting in version 4.2 of the mongo shell, you can use the passwordPrompt() method in conjunction with various user authentication/management methods/commands to prompt for the password instead of specifying the password directly in the method/command call. However, you can still specify the password directly as you would with earlier versions of the mongo shell.

copy

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.

copy

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.

8

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:

Tip

Starting in version 4.2 of the mongo shell, you can use the passwordPrompt() method in conjunction with various user authentication/management methods/commands to prompt for the password instead of specifying the password directly in the method/command call. However, you can still specify the password directly as you would with earlier versions of the mongo shell.

copy

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.

9

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.

← Deploy Replica Set With Keyfile Authentication Update Replica Set to Keyfile Authentication (No Downtime) →