Use x.509 Certificates to Authenticate Clients¶

On this page

New in version 2.6.

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.

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

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.

Procedures¶

Configure Replica Set/Sharded Cluster¶

Outside of rolling upgrade procedures, every component of a replica set or sharded cluster should use the same --clusterAuthMode setting to ensure it can securely connect to all other components in the deployment.

For replica set deployments, this includes all mongod members of the replica set.

For sharded cluster deployments, this includes all mongod and mongos instances.

Note

If you are configuring a standalone mongod, omit the --clusterAuthMode option.

Use Command-line Options¶

You can configure the MongoDB server from the command line, e.g.:

mongod --clusterAuthMode x509 --sslMode requireSSL --sslPEMKeyFile <path to SSL certificate and key PEM file> --sslCAFile <path to root CA PEM file>

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.

Use Configuration File¶

You may also specify these options in the configuration file.

Starting in MongoDB 2.6, you can specify the configuration for MongoDB in YAML format, e.g.:

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

For backwards compatibility, you can also specify the configuration using the older configuration file format, e.g.:

clusterAuthMode = x509
sslMode = requireSSL
sslPEMKeyFile = <path to TLS/SSL certificate and key PEM file>
sslCAFile = <path to the root CA PEM file>

Include any additional options, TLS/SSL or otherwise, that are required for your specific configuration.

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

Note

The RDNs in the subject string must be compatible with the RFC2253 standard.

You can retrieve the RFC2253 formatted subject from the client certificate with the following command:

openssl x509 -in <pathToClient PEM> -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-----

Add the RFC2253 compliant value of the subject as a user. Omit spaces as needed.

For example, in the mongo shell, to add the user with both the readWrite role in the test database and the userAdminAnyDatabase role which is defined only in the admin database:
```
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 }
  }
)
```
In the above example, to add the user with the readWrite role in the test database, the role specification document specified 'test' in the db field. To add userAdminAnyDatabase role for the user, the above example specified 'admin' in the db field.

Note

Some roles are defined only in the admin database, including: clusterAdmin, readAnyDatabase, readWriteAnyDatabase, dbAdminAnyDatabase, and userAdminAnyDatabase. To add a user with these roles, specify 'admin' in the db.

See Manage Users and Roles for details on adding a user with roles.

Authenticate with a x.509 Certificate¶

To authenticate with a client certificate, you must first add a MongoDB user that corresponds to the client certificate. See Add x.509 Certificate subject as a User.

To authenticate, use the db.auth() method in the $external database, specifying "MONGODB-X509" for the mechanism field, and the user that corresponds to the client certificate for the user field.

For example, if using the mongo shell,

Connect mongo shell to the mongod set up for SSL:

mongo --ssl --sslPEMKeyFile <path to CA signed client PEM file> --sslCAFile <path to root CA PEM file>

To perform the authentication, use the db.auth() method in the $external database. For the mechanism field, specify "MONGODB-X509", and for the user field, specify the user, or the subject, that corresponds to the client certificate.
```
db.getSiblingDB("$external").auth(
  {
    mechanism: "MONGODB-X509",
    user: "CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry"
  }
)
```

← x.509 Enterprise Authentication Mechanisms →