MongoDB supports x.509 certificate authentication for client authentication and internal authentication of the members of replica sets and sharded clusters.
x.509 certificate authentication requires a secure TLS/SSL connection.
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.
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 Certificates¶
To authenticate to servers, clients can use x.509 certificates instead of usernames and passwords.
Client Certificate Requirements¶
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.
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
If the MongoDB deployment has
tlsX509ClusterAuthDNOverrideset (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
DCcombination as the Member x.509 Certificate (or
tlsX509ClusterAuthDNOverrideif set), the client connection is rejected. Only cluster member x509 certificates should use same
DCcombinations as this grants full permissions.
The x.509 certificate must not be expired.
Changed in version 4.4:
mongoslogs a warning on connection if the presented x.509 certificate expires within
30days of the
mongod/mongoshost system time. See x.509 Certificates Nearing Expiry Trigger Warnings for more information.
MongoDB User and
To authenticate with a client certificate, you must first add the value
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.
Add the user in the
$external database; i.e. the
Authentication Database is the
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.
To connect and authenticate using x.509 client certificate:
For MongoDB 4.2 or greater, include the following options for the client:
For MongoDB 4.0 and earlier, include the following options for the client:
You can also make the TLS/SSL connection first, and then use
db.auth() in the
$external database to authenticate.
For examples of both cases, see the Authenticate with a x.509 Certificate (Using
section in Use x.509 Certificates to Authenticate Clients
Member x.509 Certificates¶
For internal authentication, members of sharded clusters and replica sets can use x.509 certificates instead of keyfiles, which use the SCRAM authentication mechanism.
Member Certificate Requirements¶
- A single Certificate Authority (CA) must issue all the x.509 certificates for the members of a sharded cluster or a replica set.
- The Distinguished Name (
DN), found in the member certificate's
subject, must specify a non-empty value for at least one of the following attributes: Organization (
O), the Organizational Unit (
OU) or the Domain Component (
The Organization attributes (