Internal/Membership Authentication

You can require that members of replica sets andsharded clusters authenticate to each other.For the internal authentication of the members, MongoDB can use eitherkeyfiles or x.509 certificates.

The selected method is used for all internal communication. For example, when aclient authenticates to a mongos using one of the supportedauthentication mechanisms,the mongos then uses the configured internal authentication method toconnect to the required mongod processes.

Note

Enabling internal authentication also enables clientauthorization.

Keyfiles

Keyfiles use SCRAM challenge and responseauthentication mechanism where the keyfiles contain the shared passwordfor the members.

Key Requirements

A key’s length must be between 6 and 1024 characters and may onlycontain characters in the base64 set. MongoDB strips whitespacecharacters (e.g. x0d, x09, and x20) for cross-platformconvenience. As a result, the following operations produce identicalkeys:

  1. echo -e "mysecretkey" > key1
  2. echo -e "my secret key" > key1
  3. echo -e "my secret key\n" > key2
  4. echo -e "my    secret    key" > key3
  5. echo -e "my\r\nsecret\r\nkey\r\n" > key4

Keyfile Format

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.

For example,

  • Single key
  • Multiple Key Strings
  • Multiple Key Sequence

If the keyfile contains a single key, you can specify the keystring with or without quotes

  1. my old secret key1

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

  1. 'my old secret key1'
  2. 'my new secret key2'

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

  1. - my old secret key1
  2. - my new secret key2

The ability to specify multiple keys in a file allows for the rollingupgrade of the keys without downtime. SeeRotate Keys for Replica Sets andRotate Keys for Sharded Clusters.

All mongod and mongos instances of adeployment must share at least one common key.

On UNIX systems, the keyfile must not have group or worldpermissions. On Windows systems, keyfile permissions are not checked.

You must store the keyfile on each server hosting the member of thereplica set or sharded clusters.

[1](1, 2) For MongoDB’s encrypted storage engine, the keyfile used for local key management can onlycontain 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, seeUpdate Replica Set to Keyfile Authentication.

x.509

Members of a replica set or sharded cluster can use x.509 certificates forinternal authentication instead of using keyfiles. MongoDB supports x.509certificate authentication for use with a secure TLS/SSL connection.

Note

Starting in version 4.0, MongoDB disables support for TLS 1.0encryption on systems where TLS 1.1+ is available. Formore details, see Disable TLS 1.0.

Member Certificate Requirements

The member certificate (net.tls.clusterFile, ifspecified, and net.tls.certificateKeyFile), used toverify membership to the sharded cluster or a replica set, must havethe following properties:

  • A single Certificate Authority (CA) must issue all the x.509certificates 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 thefollowing attributes: Organization (O), the Organizational Unit(OU) or the Domain Component (DC).

  • The Organization attributes (O’s), the Organizational Unitattributes (OU’s), and the Domain Components (DC’s) mustmatch those from the certificates for the other cluster members(or the tlsX509ClusterAuthDNOverride value, if set).

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

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

  1. CN=host1,OU=Dept1,O=MongoDB,ST=NY,C=US
  2. C=US, ST=CA, O=MongoDB, OU=Dept1, CN=host2

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

  1. CN=host1,OU=Dept1,OU=Sales,O=MongoDB
  2. CN=host2,OU=Dept1,O=MongoDB
  • Either the Common Name (CN) or one of the Subject AlternativeName (SAN) entries must match the hostname of the server, usedby the other members of the cluster. Starting in MongoDB 4.2, whenperforming comparison of SAN, MongoDB supports comparison of DNSnames or IP addresses. In previous versions, MongoDB only supportscomparisons of DNS names.

For example, the certificates for a cluster could have the followingsubjects:

  1. subject= CN=<myhostname1>,OU=Dept1,O=MongoDB,ST=NY,C=US
  2. subject= CN=<myhostname2>,OU=Dept1,O=MongoDB,ST=NY,C=US
  3. 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 ClientAuthentication”).
  1. extendedKeyUsage = clientAuth

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

MongoDB Configuration

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

However, if no cluster file is specified, members can use theircertificate key file specified innet.tls.certificateKeyFile or—tlsCertificateKeyFile(both new in MongoDB 4.2) for membership authentication. Thiscertificate key file is usedby mongod (and mongos) instances to prove their identityto clients, but can also be used for membership authentication. Touse 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 thecorreponding —sslClusterFile) and net.ssl.PEMKeyFile (and thecorresponding —sslPEMKeyFile)are deprecated as of MongoDB 4.2.

For deployments using MongoDB version 4.0 and earlier, usenet.ssl.clusterFile (or the corresponding—sslClusterFile) andnet.ssl.PEMKeyFile (or the corresponding—sslPEMKeyFile).

Next Steps

For an example of x.509 internal authentication, seeUse 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.