x.509

Client Certificate Requirements

The client certificate must have the following properties:

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

• Client certificates must contain the following fields:

  keyUsage = digitalSignature
  extendedKeyUsage = clientAuth

• Each unique MongoDB user must have a unique certificate.

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

  Warning

  If a client x.509 certificate's subject has the same O, OU, and DC combination as the Member x.509 Certificate (or tlsX509ClusterAuthDNOverride if set), the client connection is rejected. Only cluster member x509 certificates should use same O, OU, and DC combinations as this grants full permissions.

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

MongoDB User and $external Database

To authenticate with a client certificate, you must first add the value of the subject from the client certificate as a MongoDB user. Each unique x.509 client certificate corresponds to a single MongoDB user; i.e. you cannot use a single client certificate to authenticate more than one MongoDB user.

Add the user in the $external database; i.e. the Authentication Database is the $external database

Authenticate

To connect and authenticate using x.509 client certificate:

• For MongoDB 4.2 or greater, include the following options for the client:

  • --tls (or the deprecated --ssl option)

  • --tlsCertificateKeyFile (or the deprecated --sslPEMKeyFile option)

  • --tlsCertificateKeyFilePassword (or the deprecated --sslPEMKeyPassword option) if the certificate key file is encrypted

  • --authenticationDatabase '$external'

  • --authenticationMechanism MONGODB-X509

• For MongoDB 4.0 and earlier, include the following options for the client:

  • --ssl

  • --sslPEMKeyFile

  • --sslPEMKeyPassword option if the --sslPEMKeyFile is encrypted.

  • --authenticationDatabase '$external'

  • --authenticationMechanism MONGODB-X509

You can also make the TLS/SSL connection first, and then use db.auth() in the $external database to authenticate.

For examples of both cases, see the Authenticate with a x.509 Certificate (Using tls Options) section in Use x.509 Certificates to Authenticate Clients

TLS Connection X509 Certificate Startup Warning

Starting in MongoDB 4.4.7, 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 which use X.509 certificate whose hostnames are specified by CommonName attributes.

Member Certificate Requirements

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.

  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.

  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

  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.

MongoDB Configuration for Membership Authentication

In addition to any TLS/SSL configurations as appropriate for your deployment, include the following to specify x.509 for internal authentication for each member of your replica set (i.e. the mongod instances) or sharded cluster (i.e. the mongod and mongos instances):

• security.clusterAuthMode or --clusterAuthMode set to x509

• net.tls.clusterFile or --tlsClusterFile (both new in MongoDB 4.2)

However, if no cluster file is specified, members can use their certificate key file specified in net.tls.certificateKeyFile or --tlsCertificateKeyFile (both new in MongoDB 4.2) for membership authentication. This certificate key file is used by mongod (and mongos) instances to prove their identity to clients, but can also be used for membership authentication. To use for both client authentication and membership authentication, the certificate must either:

• Omit extendedKeyUsage or

• Specify extendedKeyUsage values

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

Next Steps

For an example of x.509 internal authentication, see Use x.509 Certificate for Membership Authentication.