Use x.509 Certificates to Authenticate Clients

On this page

MongoDB supports x.509 certificate authentication for use with a secure TLS/SSL connection. The x.509 client authentication allows clients to authenticate to servers with certificates rather than with a username and password. The following tutorial outlines the steps to use x.509 for client authentication.

See also

To use x.509 authentication for the internal authentication of replica set/sharded cluster members, see Use x.509 Certificate for Membership Authentication.

Prerequisites

Important

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

Warning

If the --sslCAFile option and its target file are not specified, x.509 client and member authentication will not function. mongod, and mongos in sharded systems, will not be able to verify the certificates of processes connecting to it against the trusted certificate authority (CA) that issued them, breaking the certificate chain.

As of version 2.6.4, mongod will not start with x.509 authentication enabled if the CA file is not specified.

Client x.509 Certificate

Note

You must have valid x.509 certificates.

Starting in MongoDB 3.6.6, if you specify --sslAllowInvalidCertificates or ssl.allowInvalidCertificates: true when using x.509 authentication, an invalid certificate is only sufficient to establish a TLS/SSL connection but is insufficient for authentication.

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 Deployment Configured for x.509

You can configure mongod/mongos for x.509 authentication from the command-line. For example, if running a replica set, each member would include the following options:

mongod --clusterAuthMode x509 --sslMode requireSSL --sslPEMKeyFile <path to TLS/SSL certificate and key PEM file> --sslCAFile <path to root CA PEM file> --replSet <name> --bind_ip <hostnames>

Include additional options as required for your configuration. For instance, if you wish remote clients to connect to your deployment or your deployment members are run on different hosts, specify the --bind_ip. For more information, see Localhost Binding Compatibility Changes.

The x.509 configuration requires:

Option Notes
--clusterAuthMode.

If the deployment is a replica set or a sharded cluster, specify x509 for all members of the replica set/sharded cluter.

Omit for standalone.

--sslMode Specify requireSSL.
--sslPEMKeyFile The instance’s x.509 certificate.
--sslCAFile Certificate Authority file to verify the certificate presented to the instance.

You can configure mongod/mongos for x.509 authentication in the configuration file. For example, if running a replica set, each member would include the following options:

security:
   clusterAuthMode: x509
net:
   ssl:
      mode: requireSSL
      PEMKeyFile: <path to TLS/SSL certificate and key PEM file>
      CAFile: <path to root CA PEM file>

Include additional options as required for your configuration. For instance, if you wish remote clients to connect to your deployment or your deployment members are run on different hosts, specify the net.bindIp setting. For more information, see Localhost Binding Compatibility Changes.

The x.509 configuration requires:

Option Notes
security.clusterAuthMode

If the deployment is a replica set or a sharded cluster, specify x509 for all members of the replica set/sharded cluter.

Omit for standalone.

net.ssl.mode Specify requireSSL.
net.ssl.PEMKeyFile The instance’s x.509 certificate.
net.ssl.CAFile Certificate Authority file to verify the certificate presented to the instance.

Procedures

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

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.

Note

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

    For example, the following 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.

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:

mongo --ssl --sslPEMKeyFile <path to CA signed client PEM file> --sslCAFile <path to root CA PEM file>  --authenticationDatabase '$external' --authenticationMechanism MONGODB-X509
Option Notes
--ssl  
--sslPEMKeyFile Client’s x.509 file.
--sslCAFile Certificate Authority file to verify the certificate presented by mongod/mongos instance.