On this page
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
mongos then uses the configured internal authentication method to
connect to the required
Enabling internal authentication also enables client authorization.
Keyfiles use SCRAM challenge and response authentication mechanism where the keyfiles contain the shared password for the members.
A key's length must be between 6 and 1024 characters and may only
contain characters in the base64 set. MongoDB strips whitespace
x20) for cross-platform
convenience. As a result, the following operations produce identical
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
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.
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.
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, 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.
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
Use member certificates to verify membership to a sharded
cluster or a replica set. Member certificates are stored in
Member certificate requirements:
A single Certificate Authority (CA) must issue all x.509 certificates for the members of a sharded cluster or a replica set.
The x.509 certificate must not be expired.
Changed in version 4.4:
mongoslogs a warning on connection if the presented x.509 certificate expires within
30days of the
mongod/mongoshost system time. See x.509 Certificates Nearing Expiry Trigger Warnings for more information.
The Distinguished Name (
DN), found in the member certificate's
subject, must specify a non-empty value for at least one of the following attributes:
the Organization (
the Organizational Unit (
the Domain Component (
Each cluster member certificate must have identical
DCs in their
net.tls.certificateKeyFilecertificates. This also applies to the
tlsX509ClusterAuthDNOverridevalue, if set. Attribute order doesn't matter.
Here's an example. The two
DNs below have matching specifications for
DCis not specified.
CN=host1,OU=Dept1,O=MongoDB,ST=NY,C=US C=US, ST=CA, O=MongoDB, OU=Dept1, CN=host2
The following example is incorrect, because the
DNs don't match. One
OUspecifications and the other has only one
Either the Common Name (
CN) or one of the Subject Alternative Name (
SAN) entries must match the server hostname for other cluster members. Starting in MongoDB 4.2, when comparing
SANs, MongoDB can compare either DNS names or IP addresses. In previous versions, MongoDB only compares DNS names.
For example, the certificates for a cluster could have the following
subject= CN=<myhostname1>,OU=Dept1,O=MongoDB,ST=NY,C=US subject= CN=<myhostname2>,OU=Dept1,O=MongoDB,ST=NY,C=US subject= CN=<myhostname3>,OU=Dept1,O=MongoDB,ST=NY,C=US
If the certificate includes the Extended Key Usage (
extendedKeyUsage) setting, the value must include
clientAuth("TLS Web Client Authentication").
extendedKeyUsage = clientAuth
You can use TLS for internal authentication between each member of
your replica set (each
mongod instance) or sharded
To use TLS for internal authentication, use the following settings:
--tlsClusterFile(available starting in MongoDB 4.2)
mongos instances use their certificate key files to
prove their identity to clients, but certificate key files can also be used for
membership authentication. If you do not specify a cluster file,
members use their certificate key files for membership authentication.
Specify the certificate key file with
(available starting in MongoDB 4.2).
To use the certificate key file for both client authentication and membership authentication, the certificate must either:
extendedKeyUsage = serverAuth, clientAuth
For an example of x.509 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.