Internal Authentication¶

On this page

Keyfiles
x.509

You can authenticate members of replica sets and sharded clusters. For the internal authentication of the members, MongoDB can use either keyfiles or x.509 certificates.

Note

Enabling internal authentication also enables client authorization.

Keyfiles¶

Keyfiles use SCRAM challenge and response authentication mechanism. The contents of the keyfiles serve as 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 characters (e.g. x0d, x09, and x20) for cross-platform convenience. As a result, the following operations produce identical keys:

copy

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

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

The content of the keyfile must be the same on all mongod and mongos instances that connect to each other. You must store the keyfile on each member of the replica set or sharded clusters.

To specify the keyfile, use the security.keyFile setting or --keyFile command line option.

For an example of keyfile internal authentication, see Enforce Keyfile Access Control in a Replica Set.

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.

Member Certificate Requirements¶

The member certificate, used for internal authentication 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 the certificates for the other cluster members. 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.

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

MongoDB Configuration¶

To specify x.509 for internal authentication, in addition to the other TLS/SSL configurations appropriate for your deployment, for each member of the replica set or sharded cluster, include either:

security.clusterAuthMode and net.ssl.clusterFile if using a configuration file, or
--clusterAuthMode and --sslClusterFile command line options.

Member Certificate and `PEMKeyFile`¶

To configure MongoDB for client certificate authentication, the mongod and mongos specify a PEMKeyFile to prove its identity to clients, either through net.ssl.PEMKeyFile setting in the configuration file or --sslPEMKeyFile command line option.

If no clusterFile certificate is specified for internal member authentication, MongoDB will attempt to use the PEMKeyFile certificate for member authentication. In order to use PEMKeyFile certificate for internal authentication as well as for client authentication, then the PEMKeyFile certificate must either:

Omit extendedKeyUsage or
Specify extendedKeyUsage values that include clientAuth in addition to serverAuth.

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.

← LDAP Authorization Enforce Keyfile Access Control in a Replica Set →