Docs Menu

Docs HomeDevelop ApplicationsMongoDB Manual

Use x.509 Certificate for Membership Authentication

On this page

  • Member x.509 Certificate
  • Configure Replica Set/Sharded Cluster
  • Additional Information

MongoDB supports x.509 certificate authentication for use with a secure TLS/SSL connection. Sharded cluster members and replica set members can use x.509 certificates to verify their membership to the cluster or the replica set instead of using keyfiles. The membership authentication is an internal process.


MongoDB disables support for TLS 1.0 encryption on systems where TLS 1.1+ is available. For more details, see Disable TLS 1.0.

Enabling internal authentication also enables Role-Based Access Control. Clients must authenticate as a user in order to connect and perform operations in the deployment.


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.


You must have valid x.509 certificates.

Starting in MongoDB 4.0, if you specify any of the following x.509 authentication options, an invalid certificate is sufficient only to establish a TLS connection but it is insufficient for authentication:

  • --sslAllowInvalidCertificates or net.ssl.allowInvalidCertificates: true for MongoDB 4.0 and later

  • --tlsAllowInvalidCertificates or net.tls.allowInvalidCertificates: true for MongoDB 4.2 and later

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.

    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.

  • Either the Common Name (CN) or one of the Subject Alternative Name (SAN) entries must match the server hostname for other cluster members. Starting in MongoDB 4.2, when comparing SANs, MongoDB can compare either DNS names or IP addresses. In previous versions, MongoDB only compares DNS names.

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

    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 used as the certificateKeyFile includes extendedKeyUsage, the value must include both clientAuth ("TLS Web Client Authentication") and serverAuth ("TLS Web Server Authentication").

    extendedKeyUsage = clientAuth, serverAuth
  • If the certificate used as the clusterFile includes extendedKeyUsage, the value must include clientAuth.

    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.

Outside of rolling upgrade procedures, every component of a replica set or sharded cluster should use the same --clusterAuthMode setting to ensure it can securely connect to all other components in the deployment.

For replica set deployments, this includes all mongod members of the replica set.

For sharded cluster deployments, this includes all mongod or mongos instances.


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.


The procedures in this section use the tls settings/option. For procedures using the deprecated ssl aliases, see Use Command-line Options (ssl).

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

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


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

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

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

To upgrade from keyfile internal authentication to x.509 internal authentication, see Upgrade from Keyfile Authentication to x.509 Authentication.

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

← Rotate Keys for Sharded Clusters