Docs4dev
Docs
mongodb / v3.6 / reference / core-security-x.509.html

x.509

On this page

New in version 2.6.

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.

Certificate Authority

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

Client x.509 Certificates

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

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.

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

    Warning

    If a client x.509 certificate’s subject has the same O, OU, and DC combination as the Member x.509 Certificate, the client will be identified as a cluster member and granted full permission on the system.

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

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

Authenticate

To authenticate using x.509 client certificate, connect to MongoDB over TLS/SSL connection; i.e. include the --ssl and --sslPEMKeyFile command line options.

Then in the $external database, use db.auth() to authenticate the user corresponding to the client certificate.

For an example, see Use x.509 Certificates to Authenticate Clients

Member x.509 Certificates

New in version 3.0.

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

Member Certificate Requirements

The member certificate, used for internal authentication 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 the certificates for the other cluster members. 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 hostname of the server, used by the other members of the cluster.

    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

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

MongoDB Configuration

To specify x.509 for internal authentication, in addition to the other TLS/SSL configurations appropriate for your deployment, for each member of the replica set or sharded cluster, include either:

Member Certificate and PEMKeyFile

To configure MongoDB for client certificate authentication, the mongod and mongos specify a PEMKeyFile to prove its identity to clients, either through net.ssl.PEMKeyFile setting in the configuration file or --sslPEMKeyFile command line option.

If no clusterFile certificate is specified for internal member authentication, MongoDB will attempt to use the PEMKeyFile certificate for member authentication. In order to use PEMKeyFile certificate for internal authentication as well as for client authentication, then the PEMKeyFile certificate must either:

  • Omit extendedKeyUsage or
  • Specify extendedKeyUsage values that include clientAuth in addition to serverAuth.

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