Note

You must have valid x.509 certificates.

Starting in MongoDB 3.6.6, if you specify --sslAllowInvalidCertificates or ssl.allowInvalidCertificates: true when using x.509 authentication, an invalid certificate is only sufficient to establish a TLS/SSL connection but is insufficient for authentication.

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

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.

Note

Starting in MongoDB 3.6, mongod and mongos bind to localhost by default. If the members of your deployment are run on different hosts or if you wish remote clients to connect to your deployment, you must specify --bind_ip or net.bindIp. For more information, see Localhost Binding Compatibility Changes.

Use Command-line Options

To specify the x.509 certificate for internal cluster member authentication, append the additional TLS/SSL options --clusterAuthMode and --sslClusterFile, as in the following example for a member of a replica set:

mongod --replSet <name> --sslMode requireSSL --clusterAuthMode x509 --sslClusterFile <path to membership certificate and key PEM file> --sslPEMKeyFile <path to TLS/SSL certificate and key PEM file> --sslCAFile <path to root CA PEM file> --bind_ip localhost,<ip address>

Include any additional options, TLS/SSL or otherwise, that are required for your specific configuration. For instance, if the membership key is encrypted, set the --sslClusterPassword to the passphrase to decrypt the key or have MongoDB prompt for the passphrase. See TLS/SSL Certificate Passphrase for details.

Use Configuration File

You can specify the configuration for MongoDB in a YAML formatted configuration file, as in the following example:

security:
   clusterAuthMode: x509
net:
   ssl:
      mode: requireSSL
      PEMKeyFile: <path to TLS/SSL certificate and key PEM file>
      CAFile: <path to root CA PEM file>
      clusterFile: <path to x.509 membership certificate and key PEM file>
   bindIp: localhost,<ip address>

See security.clusterAuthMode, net.ssl.mode, net.ssl.PEMKeyFile, net.ssl.CAFile, and net.ssl.clusterFile for more information on the settings.