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.

Client x.509 Certificate

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:

  copy

  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

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>

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

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.

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

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

Authenticate with a x.509 Certificate

mongo --ssl --sslPEMKeyFile <path to CA signed client PEM file> --sslCAFile <path to root CA PEM file>  --authenticationDatabase '$external' --authenticationMechanism MONGODB-X509