Use x.509 Certificates to Authenticate Clients¶

On this page

Prerequisites
Procedures

Note

Starting in version 4.0, MongoDB disables support for TLS 1.0 encryption on systems where TLS 1.1+ is available. For more details, see Disable TLS 1.0.

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 with a standalone mongod instance.

To use x.509 authentication for replica sets or sharded clusters, 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.

Important

To use x.509 authentication, --tlsCAFile or net.tls.CAFile must be specified unless using --tlsCertificateSelector or --net.tls.certificateSelector. Or if using the ssl aliases, --sslCAFile or net.ssl.CAFile must be specified unless using --sslCertificateSelector or net.ssl.certificateSelector.

Client x.509 Certificate¶

Note

You must have valid x.509 certificates.

Starting in MongoDB 4.0, if you specify --sslAllowInvalidCertificates or net.ssl.allowInvalidCertificates: true (or in MongoDB 4.2, the alias --tlsAllowInvalidateCertificates or net.tls.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:

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.

At least one of the Organization (O), Organizational Unit (OU), or Domain Component (DC) attributes in the client certificate must differ from those in the net.tls.clusterFile and net.tls.certificateKeyFile server certificates.

If the MongoDB deployment has tlsX509ClusterAuthDNOverride set (available starting in MongoDB 4.2), the client x.509 certificate’s subject must also differ from 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)¶

Note

The procedures in this section use the tls settings/option (Available in MongoDB 4.2). For procedures using their ssl aliases, see MongoDB Deployment Configured for x.509 (Using SSL Options).

The tls settings/options provide identical functionality as the ssl options since MongoDB has always supported TLS 1.0 and later.

Command-Options
Configuration File

You can configure a mongod instance for x.509 authentication from the command-line. For example, to configure a standalone mongod instance:

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. 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
`--tlsMode`	Specify `requireTLS`.
`--tlsCertificateKeyFile`	The instance’s x.509 certificate to present to clients.
`--tlsCAFile`	Certificate Authority file to verify the certificates presented to the instance.

You can configure mongod for x.509 authentication in the configuration file. For example, to configure a standalone mongod instance:

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. 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
`net.tls.mode`	Specify `requireTLS`.
`net.tls.certificateKeyFile`	The instance’s x.509 certificate.
`net.tls.CAFile`	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.

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

Note

The procedures in this section use the ssl settings/option. For procedures using their tls aliases (Available in MongoDB 4.2), see MongoDB Deployment Configured for x.509 (Using TLS Options).

The tls settings/options provide identical functionality as the ssl options since MongoDB has always supported TLS 1.0 and later.

Command-Options
Configuration File

You can configure a mongod instance for x.509 authentication from the command-line. For example, to configure a standalone mongod instance:

copy

mongod --sslMode requireSSL --sslPEMKeyFile <path to TLS/SSL certificate and key PEM file> --sslCAFile <path to root CA PEM file>  --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 for a standalone requires:

Option	Notes
`--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 for x.509 authentication in the configuration file. For example, to configure a standalone mongod instance:

copy

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 for a standalone requires:

Option	Notes
`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.

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

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.

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

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

Note

The procedures in this section use the tls settings/option (Available in MongoDB 4.2). For procedures using their ssl aliases, see Authenticate with a x.509 Certificate (Using ssl Options).

The tls settings/options provide identical functionality as the ssl options since MongoDB has always supported TLS 1.0 and later.

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

Connect with Authentication
Authenticate after Connection

To authenticate during connection:

copy

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

Option	Notes
`--tls`
`--tlsCertificateKeyFile`	Client’s x.509 file.
`--tlsCAFile`	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 the mongo shell,

Connect mongo shell to the mongod set up for TLS/SSL:
copy
```
mongo --tls --tlsCertificateKeyFile <path to client PEM file> --tlsCAFile <path to root CA PEM file>
```
Option Notes

--tls

--tlsCertificateKeyFile Client’s x.509 file.

--tlsCAFile Certificate Authority file to verify the certificate presented by mongod/mongos instance.
To perform the authentication, use the db.auth() method in the $external database. For the mechanism field, specify "MONGODB-X509".
copy
```
db.getSiblingDB("$external").auth(
  {
    mechanism: "MONGODB-X509"
  }
)
```

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

Note

The procedures in this section use the ssl settings/options. For procedures using their tls (Available in MongoDB 4.2) aliases, see Authenticate with a x.509 Certificate (Using tls Options).

The tls settings/options provide identical functionality as the ssl options since MongoDB has always supported TLS 1.0 and later.

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

Connect with Authentication
Authenticate after Connection

To authenticate during connection:

copy

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.
`--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 the mongo shell,

Connect mongo shell to the mongod set up for TLS/SSL:
copy
```
mongo --ssl --sslPEMKeyFile <path to CA signed client PEM file> --sslCAFile <path to root CA PEM file>
```
Option Notes

--ssl

--sslPEMKeyFile Client’s x.509 file.

--sslCAFile Certificate Authority file to verify the certificate presented by mongod/mongos instance.
To perform the authentication, use the db.auth() method in the $external database. For the mechanism field, specify "MONGODB-X509".
copy
```
db.getSiblingDB("$external").auth(
  {
    mechanism: "MONGODB-X509"
  }
)
```

← x.509 Enterprise Authentication Mechanisms →

Use x.509 Certificates to Authenticate Clients¶

Prerequisites¶

Certificate Authority¶

Client x.509 Certificate¶

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

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

Procedures¶

Add x.509 Certificate subject as a User¶

Authenticate with a x.509 Certificate (Using tls Options)¶

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

Add x.509 Certificate `subject` as a User¶

Authenticate with a x.509 Certificate (Using `tls` Options)¶

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