Docs Menu

Docs HomeMongoDB Manual

Use x.509 Certificates to Authenticate Clients

On this page

  • Prerequisites
  • Procedure
  • Next Steps

The following procedure sets up x.509 certificate authentication for client authentication on a standalone mongod instance.

To use x.509 authentication for replica sets or sharded clusters, see Use x.509 Certificate for Membership Authentication.

A full description of TLS/SSL, PKI (Public Key Infrastructure) certificates, in particular x.509 certificates, and Certificate Authority is beyond the scope of this document. This tutorial assumes prior knowledge of TLS/SSL as well as access to valid x.509 certificates.

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 use x.509 authentication, --tlsCAFile or net.tls.CAFile must be specified unless you are using --tlsCertificateSelector or --net.tls.certificateSelector.

You must have valid x.509 certificates. The client x.509 certificates must meet the client certificate requirements.

Starting in MongoDB 4.0, if you specify any of the following x.509 authentication options, an invalid certificate is sufficient only to establish a TLS connection but it is insufficient for authentication:

  • --sslAllowInvalidCertificates or net.ssl.allowInvalidCertificates: true for MongoDB 4.0 and later

  • --tlsAllowInvalidCertificates or net.tls.allowInvalidCertificates: true for MongoDB 4.2 and later

1

To set up x.509 authentication for replica sets or sharded clusters, see Use x.509 Certificate for Membership Authentication.

2

To authenticate with a client certificate, you must first add the value of the subject from the client certificate as a MongoDB user to the $external database. 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.

Note

Username Requirements

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

  • The RDNs in the subject string must be compatible with the RFC2253 standard.

  1. You can retrieve the RFC2253 formatted subject from the client certificate with the following command:

    openssl x509 -in <pathToClientPEM> -inform PEM -subject -nameopt RFC2253

    The command returns the subject string and the certificate:

    subject= CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry
    -----BEGIN CERTIFICATE-----
    # ...
    -----END CERTIFICATE-----
  2. Add the RFC2253 compliant value of the subject as a user. Omit spaces as needed.

    The following example adds a user and grants the user readWrite role in the test database and the userAdminAnyDatabase role:

    db.getSiblingDB("$external").runCommand(
    {
    createUser: "CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry",
    roles: [
    { role: "readWrite", db: "test" },
    { role: "userAdminAnyDatabase", db: "admin" }
    ],
    writeConcern: { w: "majority" , wtimeout: 5000 }
    }
    )

    See Manage Users and Roles for details on adding a user with roles.

3

After you have added the x.509 client certificate subject as a corresponding MongoDB user, you can authenticate with the client certificate:

To use x.509 authentication for replica sets or sharded clusters, see Use x.509 Certificate for Membership Authentication.

←  x.509Kerberos Authentication →