Self-Managed Internal/Membership Authentication
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
authentication mechanisms,
the mongos
then uses the configured internal authentication method to
connect to the required mongod
processes.
Note
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
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.
For example,
If the keyfile contains a single key, you can specify the key string with or without quotes:
my old secret key1
You can specify multiple key strings [1] as a sequence of key strings (optionally enclosed in quotes):
- my old secret key1 - my new secret key2
The ability to specify multiple keys in a file allows for the rolling upgrade of the keys without downtime. See Rotate Keys for Self-Managed Replica Sets and Rotate Keys for Self-Managed 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] | 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 Self-Managed 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.
Note
MongoDB disables support for TLS 1.0 encryption on systems where TLS 1.1+ is available.
Member Certificate Requirements
Use member certificates to verify membership to a sharded
cluster or a replica set. Member certificate file paths are
configured with the net.tls.clusterFile
and
net.tls.certificateKeyFile
options. Members have the
following configuration requirements:
Cluster member configuration must specify a non-empty value for at least one of the attributes used for authentication. By default, MongoDB accepts:
the Organization (
O
)the Organizational Unit (
OU
)the Domain Component (
DC
)
You can specify alternative attributes to use for authentication by setting
net.tls.clusterAuthX509.extensionValue
.Cluster member configuration must include the same
net.tls.clusterAuthX509.attributes
and use matching values. Attribute order doesn't matter. The following example setsO
andOU
, but notDC
:net: tls: clusterAuthX509: attributes: O=MongoDB, OU=MongoDB Server
The certificates have the following requirements:
A single Certificate Authority (CA) must issue all x.509 certificates for the members of a sharded cluster or a replica set.
At least one of the Subject Alternative Name (
SAN
) entries must match the server hostname used by other cluster members. When comparingSAN
s, MongoDB can compare either DNS names or IP addresses.If you don't specify
subjectAltName
, MongoDB compares the Common Name (CN) instead. However, this usage of CN is deprecated per RFC2818If the certificate used as the
certificateKeyFile
includesextendedKeyUsage
, the value must include bothclientAuth
("TLS Web Client Authentication") andserverAuth
("TLS Web Server Authentication").extendedKeyUsage = clientAuth, serverAuth If the certificate used as the
clusterFile
includesextendedKeyUsage
, the value must includeclientAuth
.extendedKeyUsage = clientAuth
MongoDB Configuration
You can use TLS for internal authentication between each member of
your replica set (each mongod
instance) or sharded
cluster (each mongod
and mongos
instance).
To use TLS for internal authentication, use the following settings:
security.clusterAuthMode
or--clusterAuthMode
set tox509
mongod
and 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 net.tls.certificateKeyFile
or
--tlsCertificateKeyFile
.
To use the certificate key file for both client authentication and membership authentication, the certificate must either:
Omit
extendedKeyUsage
orSpecify
extendedKeyUsage = serverAuth, clientAuth
Next Steps
For an example of x.509 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.