Docs Menu

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.2, if you specify --tlsAllowInvalidateCertificates or net.tls.allowInvalidCertificates: true when using x.509 authentication, an invalid certificate is only sufficient to establish a TLS connection but it is insufficient for authentication.

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

Give Feedback
MongoDB logo
© 2021 MongoDB, Inc.

About

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