Use x.509 Certificate for Membership Authentication

Use x.509 Certificate for Membership Authentication

New in version 2.6.

MongoDB supports x.509 certificate authentication for use with a secureTLS/SSL connection. Sharded clustermembers and replica set members can use x.509 certificates to verifytheir membership to the cluster or the replica set instead of usingkeyfiles. The membership authentication isan internal process.

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.

Enabling internal authentication also enablesRole-Based Access Control. Clients must authenticate as a user in order toconnect and perform operations in the deployment.

See the Manage Users and Roles tutorial forinstructions on adding users to the deployment.
See the Use x.509 Certificates to Authenticate Clients tutorialfor instructions on using x.509 certificates for user authentication.

Important

A full description of TLS/SSL, PKI (Public Key Infrastructure) certificates, in particular x.509 certificates, and Certificate Authority is beyond the scope of this document.This tutorial assumes prior knowledge of TLS/SSL as well as access to valid x.509 certificates.

Member x.509 Certificate

Note

You must have valid x.509 certificates.

Starting in MongoDB 4.0, if you specify—sslAllowInvalidCertificates ornet.ssl.allowInvalidCertificates: true (or in MongoDB 4.2, thealias —tlsAllowInvalidateCertificates ornet.tls.allowInvalidCertificates: true) when using x.509authentication, an invalid certificate is only sufficient toestablish a TLS/SSL connection but is insufficient forauthentication.

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.

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 theOU attribute since one contains two OU specifications andthe other, only one specification.

CN=host1,OU=Dept1,OU=Sales,O=MongoDB
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:

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

extendedKeyUsage = clientAuth

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

Configure Replica Set/Sharded Cluster

Outside of rolling upgrade procedures, every component of a replicaset or sharded cluster should use the same—clusterAuthMode setting to ensure it can securely connect to allother components in the deployment.

For replica set deployments, this includes all mongodmembers of the replica set.

For sharded cluster deployments, this includes all mongodor mongos instances.

Note

Starting in MongoDB 3.6, mongod and mongosbind to localhost by default. If the members of your deployment arerun on different hosts or if you wish remote clients to connect toyour deployment, you must specify —bind_ip ornet.bindIp. For more information, seeLocalhost Binding Compatibility Changes.

Use Command-line Options (tls)

Note

The procedures in this section use the ssl settings/option. Forprocedures using their tls aliases (Available in MongoDB 4.2),see Use Command-line Options (tls).

The tls settings/options provide identical functionalityas the ssl options since MongoDB has always supported TLS 1.0and later.

TLS (Command-Line Options)
TLS (Configuration File)

mongod --replSet <name> --tlsMode requireTLS --clusterAuthMode x509 --tlsClusterFile <path to membership certificate and key PEM file> --tlsCertificateKeyFile <path to TLS/SSL certificate and key file> --sslCAFile <path to root CA file> --bind_ip localhost,<hostname(s)|ip address(es)>

Important

To use x.509 authentication, —tlsCAFile or net.tls.CAFilemust be specified unless using —tlsCertificateSelector or—net.tls.certificateSelector. Or if using the ssl aliases,—sslCAFile or net.ssl.CAFile must be specified unless using—sslCertificateSelector or net.ssl.certificateSelector.

Include any additional options, TLS/SSL or otherwise, thatare required for your specific configuration. For

security:
   clusterAuthMode: x509
net:
   tls:
      mode: requireTLS
      certificateKeyFile: <path to its TLS/SSL certificate and key file>
      CAFile: <path to root CA PEM file to verify received certificate>
      clusterFile: <path to its certificate key file for membership authentication>
   bindIp: localhost,<hostname(s)|ip address(es)>

Important

Include any additional options, TLS/SSL or otherwise, thatare required for your specific configuration.

For more information, see Configure mongod and mongos for TLS/SSL.

Use Command-line Options (ssl)

Note

The procedures in this section use the ssl settings/option. Forprocedures using their tls aliases (Available in MongoDB 4.2),see Use Command-line Options (tls).

The tls settings/options provide identical functionalityas the ssl options since MongoDB has always supported TLS 1.0and later.

SSL (Command-Line Options)
SSL (Configuration File)

To specify the x.509 certificate for internal cluster memberauthentication, append the additional TLS/SSL options—clusterAuthMode and —sslClusterFile, as in thefollowing 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,<hostname(s)|ip address(es)>

Important

Include any additional options, TLS/SSL or otherwise, thatare required for your specific configuration.

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,<hostname(s)|ip address(es)>

Important

Include any additional options, TLS/SSL or otherwise, thatare required for your specific configuration.

For more information, see Configure mongod and mongos for TLS/SSL.

Additional Information

To upgrade from keyfile internal authentication to x.509 internalauthentication, seeUpgrade from Keyfile Authentication to x.509 Authentication.

To perform a rolling update of the certificates to new certificateswith different DN, seeRolling Update of x.509 Cluster Certificates that Contain New DN.