- Update Replica Set to Keyfile Authentication
- Overview
- Considerations
- Enforce Keyfile Access Control on Existing Replica Set
- Create a keyfile.
- Copy the keyfile to each replica set member.
- Shut down all members of the replica set.
- Restart each member of the replica set with access control enforced.
- Connect to the primary using the localhost interface.
- Create the user administrator.
- Authenticate as the User Administrator.
- Create the cluster administrator (Optional).
- Create additional users (Optional).
- x.509 Internal Authentication
Update Replica Set to Keyfile Authentication
Overview
Enforcing access control on an existing replica set requiresconfiguring:
- Security between members of the replica set usingInternal Authentication, and
- Security between connecting clients and the replica set usingUser Access Controls.
For this tutorial, each member of the replica set uses the same internalauthentication mechanism and settings.
Enforcing internal authentication also enforces user access control. Toconnect to the replica set, clients like the mongo
shell need touse a user account. SeeUsers.
Cloud Manager and Ops Manager
If Cloud Manager or Ops Manager is managing your deployment, see theCloud Manager manual or the OpsManager manual forenforcing access control.
Considerations
Tip
When possible, use a logical DNS hostname instead of an ip address,particularly when configuring replica set members or sharded clustermembers. The use of logical DNS hostnames avoids configurationchanges due to ip address changes.
IP Binding
Changed in version 3.6.
Starting with MongoDB 3.6, MongoDB binaries, mongod
andmongos
, bind to localhost
by default.From MongoDB versions 2.6 to 3.4, only the binaries from theofficial MongoDB RPM (Red Hat, CentOS, Fedora Linux, and derivatives)and DEB (Debian, Ubuntu, and derivatives) packages would bind tolocalhost
by default. To learn more about this change, seeLocalhost Binding Compatibility Changes.
Operating System
This tutorial uses the mongod
programs. Windows users shoulduse the mongod.exe
program instead.
Keyfile Security
Keyfiles are bare-minimum forms of security and are best suited for testing ordevelopment environments. For production environments we recommend usingx.509 certificates.
Users
This tutorial covers creating the minimum number of administrativeusers on the admin
database only. For the user authentication,the tutorial uses the default SCRAMauthentication mechanism. Challenge-response security mechanisms arebest suited for testing or development environments. For productionenvironments, we recommend using x.509certificates 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 bestpractices for user creation and management.
Downtime
The following procedure for enforcing access control requires downtime.For a procedure that does not require downtime, seeUpdate Replica Set to Keyfile Authentication (No Downtime)instead.
Enforce Keyfile Access Control on Existing Replica Set
Create a keyfile.
With keyfile authentication, eachmongod
instances in the replica set uses the contents of the keyfile as theshared password for authenticating other members in the deployment. Onlymongod
instances with the correct keyfile can join the replica set.
Note
Starting in MongoDB 4.2, keyfiles for internal membershipauthentication use YAML format to allow formultiple 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-keykeyfiles that use the text file format.
A key’s length must be between 6 and 1024 characters and may onlycontain characters in the base64 set. All members of thereplica set must share at least one common key.
Note
On UNIX systems, the keyfile must not have group or worldpermissions. 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 complexpseudo-random 1024 character string to use as a shared password. It thenuses chmod
to change file permissions to provide readpermissions for the file owner only:
- openssl rand -base64 756 > <path-to-keyfile>
- chmod 400 <path-to-keyfile>
See Keyfiles for additional details and requirementsfor 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 thefile and can access the keyfile.
Avoid storing the keyfile on storage mediums that can be easilydisconnected from the hardware hosting the mongod
instances, such as aUSB 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 thesecondaries. Continue until all members of thereplica set are offline, including any arbiters.The primary must be the last member shut down to avoidpotential rollbacks.
To shut down a mongod
, connect each mongod
using amongo
shell and issue the db.shutdownServer()
on theadmin
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 eachmongod
in the replica set with either thesecurity.keyFile
configuration file setting or the—keyFile
command-line option. Running mongod
withthe —keyFile
command-line option or thesecurity.keyFile
configuration file setting enforces bothInternal/Membership Authentication andRole-Based Access Control.
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 requiredfor your configuration. For instance, if you wish remote clients toconnect to your deployment or your deployment members are run ondifferent hosts, specify the net.bindIp
setting. For moreinformation, see Localhost Binding Compatibility Changes.
- 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, seeconfiguration 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. Forinstance, if you wish remote clients to connect to your deploymentor your deployment members are run on different hosts, specify the—bind_ip
. For more information, seeLocalhost Binding Compatibility Changes.
- 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 clustermembers. The use of logical DNS hostnames avoids configurationchanges due to ip address changes.
For more information on command-line options, see themongod
reference page.
Connect to the primary using the localhost interface.
Connect a mongo
shell to one of themongod
instances over the localhostinterface. You must run the mongo
shell on the same physical machine as the mongod
instance.
Use rs.status()
to identify the primary replica setmember. If you are connected to the primary, continue to the nextstep. If not, connect a mongo
shell to the primaryover the localhostinterface.
Important
You must connect to the primary before proceeding.
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, suchas a user with the userAdminAnyDatabase
. This ensuresthat you can create additional users after the Localhost Exceptioncloses.
If at least one user does not have privileges to create users,once the localhost exception closes you may be unable to createor modify users with new privileges, and therefore unable toaccess necessary operations.
Add a user using the db.createUser()
method. The user shouldhave at minimum the userAdminAnyDatabase
role on theadmin
database.
You must be connected to the primary to create users.
The following example creates the user fred
with theuserAdminAnyDatabase
role on the admin
database.
Important
Passwords should be random, long, and complex to ensure system securityand to prevent or delay malicious access.
Tip
Starting in version 4.2 of the mongo
shell, you canuse the passwordPrompt()
method in conjunction withvarious user authentication/management methods/commands to promptfor the password instead of specifying the password directly in themethod/command call. However, you can still specify the passworddirectly as you would with earlier versions of themongo
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 andrelated to database administration operations.
Authenticate as the User Administrator.
Authenticate to the admin
database.
In the mongo
shell, use db.auth()
toauthenticate. For example, the following authenticate as the useradministrator fred
:
Tip
Starting in version 4.2 of the mongo
shell, you canuse the passwordPrompt()
method in conjunction withvarious user authentication/management methods/commands to promptfor the password instead of specifying the password directly in themethod/command call. However, you can still specify the passworddirectly as you would with earlier versions of themongo
shell.
- db.getSiblingDB("admin").auth("fred", passwordPrompt()) // or cleartext password
Alternatively, connect a new mongo
shell to the primaryreplica set member using the -u <username>
, -p <password>
, andthe —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 thepassword.
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 theclusterAdmin
role in the admin
database:
Tip
Starting in version 4.2 of the mongo
shell, you canuse the passwordPrompt()
method in conjunction withvarious user authentication/management methods/commands to promptfor the password instead of specifying the password directly in themethod/command call. However, you can still specify the passworddirectly as you would with earlier versions of themongo
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 toreplica 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 creatingread-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, seeUse x.509 Certificate for Membership Authentication.
To upgrade from keyfile internal authentication to x.509 internalauthentication, seeUpgrade from Keyfile Authentication to x.509 Authentication.