Docs Menu
Docs Home
/
MongoDB Manual
/
Self-Managed Deployments
/
Security
/
Authentication
/
Internal

Use x.509 Certificate for Membership Authentication with Self-Managed MongoDB

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.

Note

MongoDB disables support for TLS 1.0 encryption on systems where TLS 1.1+ is available.

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

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.

If you specify --tlsAllowInvalidCertificates or net.tls.allowInvalidCertificates: true, an invalid certificate is sufficient only to establish a TLS connection but it is insufficient for authentication.

Certificate Requirements

Use member certificates to verify membership to a sharded cluster or a replica set. Member certificates are stored in net.tls.clusterFile and net.tls.certificateKeyFile. Member certificate requirements:

  • A single Certificate Authority (CA) must issue all x.509 certificates for the members of a sharded cluster or a replica set.

  • The x.509 certificate must not be expired.

    Note

    mongod / mongos logs a warning on connection if the presented x.509 certificate expires within 30 days of the mongod/mongos host system time.

  • 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:

    • the Organization (O)

    • the Organizational Unit (OU)

    • the Domain Component (DC)

  • In multi-cluster deployments, each cluster must use a different X.509 member certificate. Each certificate must have unique values on the O, OU, and DC Distinguished Name (DN) fields.

    If two clusters have certificates with the same DN values, a compromised server on one cluster can authenticate as a member of the other.

  • Each cluster member certificate must have identical Os, OUs, and DCs in their net.tls.clusterFile and net.tls.certificateKeyFile certificates. This also applies to the tlsX509ClusterAuthDNOverride value, if set. Attribute order doesn't matter.

    Here's an example. The two DNs below have matching specifications for O and OU, and DC is not specified.

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

    The following example is incorrect, because the DNs don't match. One DN has two OU specifications and the other has only one OU 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 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

Configure Replica Set/Sharded Cluster

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.

Note

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.

Use Command-line Options (tls)

Note

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.

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.CAFile must be specified unless you are using --tlsCertificateSelector or --net.tls.certificateSelector.

Include any additional options, TLS/SSL or otherwise, that are 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

To use x.509 authentication, --tlsCAFile or net.tls.CAFile must be specified unless you are using --tlsCertificateSelector or --net.tls.certificateSelector.

Include any additional options, TLS/SSL or otherwise, that are 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 deprecated ssl settings/option. For procedures that use tls aliases, 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.

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

Important

To use x.509 authentication, --tlsCAFile or net.tls.CAFile must be specified unless you are using --tlsCertificateSelector or --net.tls.certificateSelector.

Include any additional options, TLS/SSL or otherwise, that are 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

To use x.509 authentication, --tlsCAFile or net.tls.CAFile must be specified unless you are using --tlsCertificateSelector or --net.tls.certificateSelector.

Include any additional options, TLS/SSL or otherwise, that are 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 internal authentication, see Upgrade Self-Managed MongoDB 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 Certificates that Contain New DN on Self-Managed Clusters.

Back

Rotate Sharded Cluster Keys

Next

Upgrade to x.509 from Keyfile