Use x.509 Certificates to Authenticate Clients

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/SSL vendors. 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:

  keyUsage = digitalSignature
  extendedKeyUsage = clientAuth

• Each unique MongoDB user must have a unique certificate.

• The subject of a client x.509 certificate, which contains the Distinguished Name (DN), must be different than the subjects of member x.509 certificates.

  Important

  If a client x.509 certificate's subject matches the O, OU, and DC attributes of the Member x.509 Certificate (or tlsX509ClusterAuthDNOverride, if set) exactly, the client connection is accepted, full permissions are granted, and a warning message appears in the log.

  Only cluster member x509 certificates should use the same O, OU, and DC attribute combinations.

  New in version 4.2: If the MongoDB deployment has tlsX509ClusterAuthDNOverride set, the client x.509 certificate's subject must not match that value.

  Warning

  If a client x.509 certificate's subject has the same O, OU, and DC combination as the Member x.509 Certificate (or tlsX509ClusterAuthDNOverride if set), the client connection is rejected. Only cluster member x509 certificates should use same O, OU, and DC combinations as this grants full permissions.

• The x.509 certificate must not be expired.

  Changed in version 4.4: mongod / mongos logs a warning on connection if the presented x.509 certificate expires within 30 days of the mongod/mongos host system time. See x.509 Certificates Nearing Expiry Trigger Warnings for more information.

MongoDB Deployment Configured for x.509 (Using TLS Options)

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

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

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

MongoDB Deployment Configured for x.509 (Using SSL Options)

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

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

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

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:

   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 (Using tls Options)

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

mongo --tls --tlsCertificateKeyFile <path to client PEM file> --tlsCAFile <path to root CA PEM file>  --authenticationDatabase '$external' --authenticationMechanism MONGODB-X509

Authenticate with a x.509 Certificate (Using ssl Options)

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

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