x.509

MongoDB supports x.509 certificate authentication for client authentication andinternal authentication of the members of replica sets and sharded clusters.

x.509 certificate authentication requires a secure TLS/SSL connection.

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.

Certificate Authority

For production use, your MongoDB deployment should use valid certificatesgenerated and signed by a single certificate authority. You or yourorganization can generate and maintain an independent certificateauthority, or use certificates generated by a third-party TLS/SSLvendor. Obtaining and managing certificates is beyond the scope ofthis documentation.

Client x.509 Certificates

To authenticate to servers, clients can use x.509 certificates insteadof usernames and passwords.

Client Certificate Requirements

The client certificate must have the followingproperties:

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

  • Client certificates must contain the following fields:

  1. keyUsage = digitalSignature
  2. extendedKeyUsage = clientAuth

  • Each unique MongoDB user must have a unique certificate.

  • A client x.509 certificate’s subject, which contains theDistinguished Name (DN), must differ from that of aMember x.509 Certificate. Specifically, the subjects mustdiffer with regards to at least one of the following attributes:Organization (O), the Organizational Unit (OU) or theDomain Component (DC).

If the MongoDB deployment hastlsX509ClusterAuthDNOverride set (available startingin MongoDB 4.2), the client x.509 certificate’s subject must alsodiffer from that value.

Warning

If a client x.509 certificate’s subject has the same O,OU, and DC combination as theMember x.509 Certificate (ortlsX509ClusterAuthDNOverride if set), the clientwill be identified as a cluster member and granted fullpermission on the system.

MongoDB User and $external Database

To authenticate with a client certificate, you must first add the valueof the subject from the client certificate as a MongoDB user. Eachunique x.509 client certificate corresponds to a single MongoDB user;i.e. you cannot use a single client certificate to authenticate morethan one MongoDB user.

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

Changed in version 3.6.3: To use sessions with $external authentication users (i.e.Kerberos, LDAP, x.509 users), the usernames cannot be greaterthan 10k bytes.

Authenticate

To connect and authenticate using x.509 client certificate:

You can also make the TLS/SSL connection first, and then usedb.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

Member x.509 Certificates

For internal authentication, members of sharded clusters and replica setscan use x.509 certificates instead of keyfiles, which use theSCRAM authentication mechanism.

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

  1. CN=host1,OU=Dept1,O=MongoDB,ST=NY,C=US
  2. 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.

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

  1. subject= CN=<myhostname1>,OU=Dept1,O=MongoDB,ST=NY,C=US
  2. subject= CN=<myhostname2>,OU=Dept1,O=MongoDB,ST=NY,C=US
  3. 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”).
  1. extendedKeyUsage = clientAuth

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

MongoDB Configuration for Membership Authentication

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

However, if no cluster file is specified, members can use theircertificate key file specified innet.tls.certificateKeyFile or—tlsCertificateKeyFile(both new in MongoDB 4.2) for membership authentication. Thiscertificate key file is usedby mongod (and mongos) instances to prove their identityto clients, but can also be used for membership authentication. Touse for both client authentication and membership authentication,the certificate must either:

  • Omit extendedKeyUsage or
  • Specify extendedKeyUsage values

Note

Athough still available, net.ssl.clusterFile (and thecorreponding —sslClusterFile) and net.ssl.PEMKeyFile (and thecorresponding —sslPEMKeyFile)are deprecated as of MongoDB 4.2.

For deployments using MongoDB version 4.0 and earlier, usenet.ssl.clusterFile (or the corresponding—sslClusterFile) andnet.ssl.PEMKeyFile (or the corresponding—sslPEMKeyFile).

Next Steps

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