Internal/Membership Authentication¶
You can require that members of replica sets and sharded clusters authenticate to each other. For the internal authentication of the members, MongoDB can use either keyfiles or x.509 certificates.
The selected method is used for all internal communication. For example, when a
client authenticates to a mongos
using one of the supported
authentication mechanisms,
the mongos
then uses the configured internal authentication method to
connect to the required mongod
processes.
Enabling internal authentication also enables client authorization.
Keyfiles¶
Keyfiles use SCRAM challenge and response authentication mechanism where the keyfiles contain the shared password for the members.
Key Requirements¶
A key's length must be between 6 and 1024 characters and may only
contain characters in the base64 set. MongoDB strips whitespace
characters (e.g. x0d
, x09
, and x20
) for cross-platform
convenience. As a result, the following operations produce identical
keys:
echo -e "mysecretkey" > key1 echo -e "my secret key" > key1 echo -e "my secret key\n" > key2 echo -e "my secret key" > key3 echo -e "my\r\nsecret\r\nkey\r\n" > key4
Keyfile Format¶
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.
For example,
If the keyfile contains a single key, you can specify the key string with or without quotes
my old secret key1
The ability to specify multiple keys in a file allows for the rolling upgrade of the keys without downtime. See Rotate Keys for Replica Sets and Rotate Keys for Sharded Clusters.
All mongod
and mongos
instances of a
deployment must share at least one common key.
On UNIX systems, the keyfile must not have group or world permissions. On Windows systems, keyfile permissions are not checked.
You must store the keyfile on each server hosting the member of the replica set or sharded clusters.
[1] | (1, 2) For MongoDB's encrypted storage engine, the keyfile used for local key management can only contain a single key . |
MongoDB Configuration for Keyfile¶
To specify the keyfile, use the security.keyFile
setting or
--keyFile
command line option.
For an example of keyfile internal authentication, see Update Replica Set to Keyfile Authentication.
x.509¶
Members of a replica set or sharded cluster can use x.509 certificates for internal authentication instead of using keyfiles. MongoDB supports x.509 certificate authentication for use with a secure TLS/SSL connection.
Starting in version 4.0, MongoDB disables support for TLS 1.0 encryption on systems where TLS 1.1+ is available. For more details, see Disable TLS 1.0.
Member Certificate Requirements¶
The member certificate (net.tls.clusterFile
, if
specified, and net.tls.certificateKeyFile
), used to
verify membership to the sharded cluster or a replica set, must have
the following properties:
- A single Certificate Authority (CA) must issue all the x.509 certificates for the members of a sharded cluster or a replica set.
- The Distinguished Name (
DN
), found in the member certificate'ssubject
, must specify a non-empty value for at least one of the following attributes: Organization (O
), the Organizational Unit (OU
) or the Domain Component (DC
). The Organization attributes (
O