Deploy Self-Managed Replica Set With Keyfile Authentication
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 Role-Based Access Control in Self-Managed Deployments.
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 mongosh
need to
use a user account. See
Users and Authentication Mechanisms.
Cloud Manager and Ops Manager
If you are currently using or are planning to use Cloud Manager or Ops Manager, see the Cloud Manager manual or the Ops Manager manual for enforcing access control.
Considerations
Important
To avoid configuration updates due to IP address changes, use DNS hostnames instead of IP addresses. It is particularly important to use a DNS hostname instead of an IP address when configuring replica set members or sharded cluster members.
Use hostnames instead of IP addresses to configure clusters across a split network horizon. Starting in MongoDB 5.0, nodes that are only configured with an IP address fail startup validation and do not start.
IP Binding
mongod
and mongos
bind to localhost by default. If the members of your deployment are
run on different hosts or if you wish remote clients to connect to
your deployment, you must specify --bind_ip
or
net.bindIp
.
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.
Users and Authentication Mechanisms
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 Self-Managed LDAP Proxy Authentication
(available for MongoDB Enterprise only) or Kerberos Authentication on Self-Managed Deployments
(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.
Deploy New Replica Set with Keyfile Access Control
Important
To avoid configuration updates due to IP address changes, use DNS hostnames instead of IP addresses. It is particularly important to use a DNS hostname instead of an IP address when configuring replica set members or sharded cluster members.
Use hostnames instead of IP addresses to configure clusters across a split network horizon. Starting in MongoDB 5.0, nodes that are only configured with an IP address fail startup validation and do not start.
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
Keyfiles for internal membership authentication use YAML format to allow for multiple keys in a keyfile. The YAML format accepts either:
A single key string (same as in earlier versions)
A 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:
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.
Start each member of the replica set with access control enabled.
For each member in the replica set, start the mongod
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
Self-Managed Internal/Membership Authentication and
Role-Based Access Control in Self-Managed Deployments.
Configuration File
If using a configuration file, set
security.keyFile
to the keyfile's path, andreplication.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.
security: keyFile: <path-to-keyfile> replication: replSetName: <replicaSetName> net: bindIp: localhost,<hostname(s)|ip address(es)>
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 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
.
mongod --keyFile <path-to-keyfile> --replSet <replicaSetName> --bind_ip localhost,<hostname(s)|ip address(es)>
Important
To avoid configuration updates due to IP address changes, use DNS hostnames instead of IP addresses. It is particularly important to use a DNS hostname instead of an IP address when configuring replica set members or sharded cluster members.
Use hostnames instead of IP addresses to configure clusters across a split network horizon. Starting in MongoDB 5.0, nodes that are only configured with an IP address fail startup validation and do not start.
For more information on command-line options, see the
mongod
reference page.
Connect to a member of the replica set over the localhost interface.
Connect mongosh
to one of the
mongod
instances over the localhost
interface. You must run mongosh
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.
Initiate the replica set.
From mongosh
, run the rs.initiate()
method.
rs.initiate()
can take an optional replica set
configuration document. In the
replica set configuration document, include:
The
_id
field set to the replica set name specified in either thereplication.replSetName
or the--replSet
option.The
members
array with a document per each member of the replica set.
The following example initates a three member replica set.
Important
Run rs.initiate()
on only one mongod
instance
for the replica set.
Important
To avoid configuration updates due to IP address changes, use DNS hostnames instead of IP addresses. It is particularly important to use a DNS hostname instead of an IP address when configuring replica set members or sharded cluster members.
Use hostnames instead of IP addresses to configure clusters across a split network horizon. Starting in MongoDB 5.0, nodes that are only configured with an IP address fail startup validation and do not start.
rs.initiate( { _id : "myReplSet", members: [ { _id : 0, host : "mongo1.example.net:27017" }, { _id : 1, host : "mongo2.example.net:27017" }, { _id : 2, host : "mongo3.example.net:27017" } ] } )
rs.initiate()
triggers an election and
elects one of the members to be the primary.
Connect to the primary before continuing. Use rs.status()
to
locate the primary member.
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 in Self-Managed Deployments
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
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.
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 related to database administration operations.
Authenticate as the user administrator.
Authenticate to the admin
database.
In mongosh
, use db.auth()
to
authenticate. For example, the following authenticate as the user
administrator fred
:
Tip
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.
db.getSiblingDB("admin").auth("fred", passwordPrompt()) // or cleartext password
Alternatively, connect a new mongosh
instance to
the primary replica set member using the -u <username>
,
-p <password>
, and the --authenticationDatabase
parameters.
mongosh -u "fred" -p --authenticationDatabase "admin"
If you do not specify the password to the -p
command-line option, mongosh
prompts for the
password.
Create the cluster administrator.
The clusterAdmin
role grants access to replication
operations, such as configuring the replica set.
Create a cluster administrator user and assign the
clusterAdmin
role in the admin
database:
Tip
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.
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 and sharded cluster 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 in Self-Managed Deployments.
x.509 Internal Authentication
For details on using x.509 for internal authentication, see Use x.509 Certificate for Membership Authentication with Self-Managed MongoDB.
To upgrade from keyfile internal authentication to x.509 internal authentication, see Upgrade Self-Managed MongoDB from Keyfile Authentication to x.509 Authentication.