Docs Menu

x.509

On this page

  • Certificate Authority
  • Client x.509 Certificates
  • Member x.509 Certificates

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

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

For production use, your MongoDB deployment should use valid certificates generated and signed by a certificate authority. You or your organization can generate and maintain an independent certificate authority, or use certificates generated by third-party TLS vendors. Obtaining and managing certificates is beyond the scope of this documentation.

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

Client certificates 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.
  • A client x.509 certificate's subject, which contains the Distinguished Name (DN), must differ from the subjects of member x.509 certificates.

    At least one of the Organization (O), Organizational Unit (OU), or Domain Component (DC) attributes in the client certificate must differ from those in the net.tls.clusterFile and net.tls.certificateKeyFile server certificates. 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.

    If the MongoDB deployment has tlsX509ClusterAuthDNOverride set (available starting in MongoDB 4.2), the client x.509 certificate's subject must also differ from that value.

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

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. You cannot use a single client certificate to authenticate more than one MongoDB user.

Add the user in the $external database. The $external database is the Authentication Database for the user.

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

For internal authentication between members of sharded clusters and replica sets you can use x.509 certificates instead of keyfiles, which use the SCRAM authentication mechanism.

Member certificates which you use to verify membership to a sharded cluster or a replica set (net.tls.clusterFile, if specified, and net.tls.certificateKeyFile), 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:

    • the Organization (O)
    • the Organizational Unit (OU)
    • 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, 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 hostname of the server, used by the other members of the cluster. Starting in MongoDB 4.2, when performing comparison of SAN, MongoDB supports comparison of DNS names or IP addresses. In previous versions, MongoDB only supports comparisons of 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
  • 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.

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:

mongod and mongos instances use their certificate key file to prove their identity to clients, but it can also be used for membership authentication. If you do not specify a cluster file, members use their certificate key file for membership authentication. The certificate key file is the file you specify 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
Give Feedback
MongoDB logo
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.