Update Replica Set to Keyfile Authentication (No Downtime)¶

Create the user administrator.¶

Connect to the primary to create a user with userAdminAnyDatabase role. The userAdminAnyDatabase role grants access to user creation on any database in the deployment.

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" } ]
  }
)

At the completion of this procedure, any client that administers users in the replica set must authenticate as this user, or a user with similar permissions.

See Database User Roles for a full list of built-in roles and related to database administration operations.

Create the cluster administrator.¶

Connect to the primary to create a user with clusterAdmin role. The clusterAdmin role grants access to replication operations, such as configuring the replica set.

The following example creates the user ravi with the clusterAdmin role on the admin database.

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

At the completion of this procedure, any client that administrates or maintains the replica set must authenticate as this user, or a user with similar permissions.

See Cluster Administration Roles for a full list of built-in roles related to replica set operations.

Create users for client applications.¶

Create users to allow client application to connect and interact with the replica set. At the completion of this tutorial, clients must authenticate as a configured user to connect to the replica set.

See Database User Roles for basic built-in roles to use in creating read-only and read-write users.

The following creates a user with read and write permissions on the foo database.

Create a user with the readWrite role in the foo database.

db.getSiblingDB("foo").createUser(
  {
    "user" : "joe",
    "pwd" :  passwordPrompt(),     // or cleartext password
    roles: [ { "role" : "readWrite", "db" : "foo" } ]
  }
)

Clients authenticating as this user can perform read and write operations against the foo database. See Authenticate a User for more on creating an authenticated connection to the replica set.

See the Add Users tutorial for more information on adding users. Consider security best practices when adding new users.

Update Client Applications¶

At this point in the procedure, the replica set does not enforce authentication. However, client applications can still specify auth credentials and connect to the replica set.

Update client applications to authenticate to the replica set using a configured user. Authenticated connections require a username, password, and the authentication database. See Authenticate a User.

For example, the following connects to a replica set named mongoRepl and authenticates as the user joe.

mongo  -u joe -password  -authenticationDatabase foo --host mongoRepl/mongo1.example.net:27017, mongo2.example.net:27017, mongo3.example.net:27017

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

If your application uses a MongoDB driver, see the associated driver documentation for instructions on creating an authenticated connection.

At the completion of this tutorial, the replica set rejects non-authenticated client connections. Performing this step now ensures clients can connect to the replica set before and after the transition.

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.

Restart each secondary or arbiter member of the replica set with transitionToAuth.¶

Restart each secondary or arbiter member in the replica set, including in the configuration:

• The security.transitionToAuth setting. Starting the mongod with security.transitionToAuth set to true places the instance in a transition state where it can accept and create both authenticated and non-authenticated connections.
• An internal authentication mechanism such as security.keyFile.

You must restart each member one at a time to ensure a majority of members in the replica set remain online.

admin = db.getSiblingDB("admin")
admin.shutdownServer()

security:
  keyFile: <path-to-keyfile>
  transitionToAuth: true
replication:
  replSetName: <replicaSetName>

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

Step down the primary member of the replica set and restart it with --transitionToAuth.¶

Step down the primary member in the replica set and restart the member, including in its configuration:

• The security.transitionToAuth setting. Starting the mongod with security.transitionToAuth set to true places the instance in a transition state where it can accept and create both authenticated and non-authenticated connections.
• An internal authentication mechanism such as security.keyFile.

rs.stepDown()

admin = db.getSiblingDB("admin")
admin.shutdownServer()

security:
  keyFile: <path-to-keyfile>
  transitionToAuth: true
replication:
  replSetName: <replicaSetName>

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

Restart secondaries and arbiters without --transitionToAuth¶

Restart each secondary or arbiter member in the replica set, removing the security.transitionToAuth option on restart. You must do this one at a time to ensure a majority of members in the replica set remain online.

If the majority of replica set members are offline at the same time, the replica set may go into read-only mode.

admin = db.getSiblingDB("admin")
admin.shutdownServer()

security:
  keyFile: <path-to-keyfile>
replication:
  replSetName: <replicaSetName>

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

Step down and restart the primary replica set member without --transitionToAuth.¶

Step down the primary member in the replica set, then restart it without the security.transitionToAuth option.

rs.stepDown()

admin = db.getSiblingDB("admin")
admin.shutdownServer()

security:
  keyFile: <path-to-keyfile>
replication:
  replSetName: <replicaSetName>

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