x.509

Client Certificate Requirements

Client certificate requirements:

• A single Certificate Authority (CA) must issue the certificates for both the client and the server.

• Each unique MongoDB user must have a unique certificate.

• The x.509 certificate must not be expired.

  Note

  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.

• Client certificates must contain the following fields:

  keyUsage = digitalSignature
  extendedKeyUsage = clientAuth

• At least one of the following client certificate attributes must be different than the attributes in both the net.tls.clusterFile and net.tls.certificateKeyFile server certificates:

  • Organization (O)

  • Organizational Unit (OU)

  • Domain Component (DC)

• The subject of a client x.509 certificate, which contains the Distinguished Name (DN), must be different than the subjects of member x.509 certificates.

  Important

  If a client x.509 certificate's subject matches the O, OU, and DC attributes of the Member x.509 Certificate (or tlsX509ClusterAuthDNOverride, if set) exactly, the client connection is accepted, full permissions are granted, and a warning message appears in the log.

  Only cluster member x509 certificates should use the same O, OU, and DC attribute combinations.

  New in version 4.2: If the MongoDB deployment has tlsX509ClusterAuthDNOverride set, the client x.509 certificate's subject must not match that value.

MongoDB User and $external Database

To authenticate with a client certificate, you must first add the client certificate's subject as a MongoDB user in the $external database. The $external database is the Authentication Database for the user.

Each unique x.509 client certificate is for one MongoDB user. You cannot use a single client certificate to authenticate more than one MongoDB user.

To use Client Sessions and Causal Consistency Guarantees with $external authentication users (Kerberos, LDAP, or x.509 users), usernames cannot be greater than 10k bytes.

TLS Connection X509 Certificate Startup Warning

Starting in MongoDB 5.0, mongod and mongos now issue a startup warning when their certificates do not include a Subject Alternative Name attribute.

The following platforms do not support common name validation:

• iOS 13 and higher

• MacOS 10.15 and higher

• Go 1.15 and higher

Clients using these platforms will not authenticate to MongoDB servers that use x.509 certificates whose hostnames are specified by CommonName attributes.

Member 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

  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.

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

• 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 includes the Extended Key Usage (extendedKeyUsage) setting, the value must include clientAuth ("TLS Web Client Authentication").

  extendedKeyUsage = clientAuth

MongoDB Configuration for Membership Authentication

You can use TLS for internal authentication between each member of your replica set (each mongod instance) or sharded cluster (each mongod and mongos instance).

To use TLS for internal authentication, use the following settings:

• security.clusterAuthMode or --clusterAuthMode set to x509

• net.tls.clusterFile or --tlsClusterFile (available starting in MongoDB 4.2)

mongod and mongos instances use their certificate key files to prove their identity to clients, but certificate key files can also be used for membership authentication. If you do not specify a cluster file, members use their certificate key files for membership authentication. Specify the certificate key file with net.tls.certificateKeyFile or --tlsCertificateKeyFile (available starting in MongoDB 4.2).

To use the certificate key file for both client authentication and membership authentication, the certificate must either:

• Omit extendedKeyUsage or

• Specify extendedKeyUsage = serverAuth, clientAuth