Navigation

Use x.509 Certificates to Authenticate Clients

On this page

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.

Prerequisites

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.

Certificate Authority

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.

Client x.509 Certificate

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.

Procedure

2

Deploy with x.509 Authentication

You can configure a mongod instance for x.509 authentication from the command-line.

To configure a standalone mongod instance, run the following command:

copy 
mongod --tlsMode requireTLS \
    --tlsCertificateKeyFile <path to TLS/SSL certificate and key PEM file> \
    --tlsCAFile <path to root CA PEM file> --bind_ip <hostnames>

Include additional options as required for your configuration.

The x.509 configuration requires:

Option Notes
--tlsMode Specify requireTLS.
--tlsCertificateKeyFile Specify the instance’s x.509 certificate to present to clients.
--tlsCAFile Specify the Certificate Authority file to verify the certificates presented to the instance.

You can configure a mongod for x.509 authentication in the configuration file.

To configure a standalone mongod instance, add the following configuration options to your configuration file:

copy 
net:
   tls:
      mode: requireTLS
      certificateKeyFile: <path to TLS/SSL certificate and key PEM file>
      CAFile: <path to root CA PEM file>

Include additional options as required for your configuration.

The x.509 configuration requires:

Option Notes
net.tls.mode Specify requireTLS.
net.tls.certificateKeyFile Specify the instance’s x.509 certificate to present to clients.
net.tls.CAFile Specify the Certificate Authority file to verify the certificates presented to the instance.

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

2

Add x.509 Certificate subject as a User

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:

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

    The command returns the subject string and the certificate:

    copy 
    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:

    copy 
    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

Authenticate with a x.509 Certificate

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

To authenticate during connection, run the following command:

copy 
mongosh --tls --tlsCertificateKeyFile <path to client PEM file> \
    --tlsCAFile <path to root CA PEM file> \
    --authenticationDatabase '$external' \
    --authenticationMechanism MONGODB-X509
Option Notes
--tls  
--tlsCertificateKeyFile Specify the client’s x.509 file.
--tlsCAFile Specify the Certificate Authority file to verify the certificate presented by the mongod instance.
--authenticationDatabase Specify '$external'.
--authenticationMechanism Specify MONGODB-X509.

You can connect without authentication and use the db.auth() method to authenticate after connection.

For example, if using mongosh,

  1. Connect mongosh to the mongod:

    copy 
    mongosh --tls --tlsCertificateKeyFile <path to client PEM file> \
    --tlsCAFile <path to root CA PEM file>
    Option Notes
    --tls  
    --tlsCertificateKeyFile Specify the client’s x.509 file.
    --tlsCAFile Specify the Certificate Authority file to verify the certificate presented by the mongod or mongos instance.

  2. To authenticate, use the db.auth() method in the $external database. For the mechanism field, specify "MONGODB-X509".

    copy 
    db.getSiblingDB("$external").auth(
  {
    mechanism: "MONGODB-X509"
  }
)

Next Steps

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

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.