Navigation

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:

copy 
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

copy 
my old secret key1

You can specify multiple key strings [1] where each key string is enclosed in quotes:

copy 
'my old secret key1'
'my new secret key2'

You can specify multiple key strings [1] as a sequence of key strings (optionally enclosed in quotes):

copy 
- 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 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.

Note

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’s subject, 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’s), the Organizational Unit attributes (OU’s), and the Domain Components (DC’s) must match those from both the net.tls.clusterFile and net.tls.certificateKeyFile certificates for the other cluster members (or the tlsX509ClusterAuthDNOverride value, if set).

    To match, the certificate must match all specifications of these attributes, or even the non-specification of these attributes. The order of the attributes does not matter.

    In the following example, the two DN’s contain matching specifications for O, OU as well as the non-specification of the DC attribute.

    copy 
    CN=host1,OU=Dept1,O=MongoDB,ST=NY,C=US
C=US, ST=CA, O=MongoDB, OU=Dept1, CN=host2

    However, the following two DN’s contain a mismatch for the OU attribute since one contains two OU specifications and the other, only one specification.

    copy 
    CN=host1,OU=Dept1,OU=Sales,O=MongoDB
CN=host2,OU=Dept1,O=MongoDB

  • Either the Common Name (CN) or one of the Subject Alternative Name (SAN) entries must match the hostname of the server, used by the other members of the cluster. Starting in MongoDB 4.2, when performing comparison of SAN, MongoDB supports comparison of DNS names or IP addresses. In previous versions, MongoDB only supports comparisons of DNS names.

    For example, the certificates for a cluster could have the following subjects:

    copy 
    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”).

    copy 
    extendedKeyUsage = clientAuth

    You can also use a certificate that does not include the Extended Key Usage (EKU).

  • The x.509 certificate must not be expired.

    Changed in version 4.4: mongod / mongos logs a warning on connection if the presented x.509 certificate expires within 30 days of the mongod/mongos host system time. See x.509 Certificates Nearing Expiry Trigger Warnings for more information.

MongoDB Configuration

In addition to any TLS/SSL configurations as appropriate for your deployment, include the following to specify x.509 for internal authentication for each member of your replica set (i.e. the mongod instances) or sharded cluster (i.e. the mongod and mongos instances):

However, if no cluster file is specified, members can use their certificate key file specified in net.tls.certificateKeyFile or --tlsCertificateKeyFile (both new in MongoDB 4.2) for membership authentication. This certificate key file is used by mongod (and mongos) instances to prove their identity to clients, but can also be used for membership authentication. To use for both client authentication and membership authentication, the certificate must either:

  • Omit extendedKeyUsage or
  • Specify extendedKeyUsage values

Note

Athough still available, net.ssl.clusterFile (and the correponding --sslClusterFile) and net.ssl.PEMKeyFile (and the corresponding --sslPEMKeyFile) are deprecated as of MongoDB 4.2.

For deployments using MongoDB version 4.0 and earlier, use net.ssl.clusterFile (or the corresponding --sslClusterFile) and net.ssl.PEMKeyFile (or the corresponding --sslPEMKeyFile).

Next Steps

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.

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.