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.
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 vendors. Obtaining and managing certificates is beyond the scope of this documentation.
To authenticate to servers, clients can use x.509 certificates instead of usernames and passwords.
Client certificate requirements:
A single Certificate Authority (CA) must issue the certificates for both the client and the server.
Each unique MongoDB user must have a unique certificate.
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.
Client certificates must contain the following fields:
keyUsage = digitalSignature extendedKeyUsage = clientAuth
Organizational Unit (
Domain Component (
subjectof a client x.509 certificate, which contains the Distinguished Name (
DN), must be different than the
subjects of member x.509 certificates.
If a client x.509 certificate's subject matches the
DCattributes 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
New in version 4.2: If the MongoDB deployment has
tlsX509ClusterAuthDNOverrideset, the client x.509 certificate's subject must not match that value.
To authenticate with a client certificate, you must first add the client
subject as a MongoDB user in the
$external database is the Authentication Database for the user.
Each unique x.509 client certificate is for one MongoDB user. You cannot use a single client certificate to authenticate more than one MongoDB user.
To use Client Sessions and Causal Consistency Guarantees with
$external authentication users
(Kerberos, LDAP, or x.509 users), usernames cannot be greater
than 10k bytes.
The following platforms do not support common name validation:
iOS 13 and higher
MacOS 10.15 and higher
Go 1.15 and higher
For internal authentication between members of sharded clusters and replica sets, you can use x.509 certificates instead of keyfiles.
Use member certificates to verify membership to a sharded
cluster or a replica set. Member certificate file paths are
configured with the
net.tls.certificateKeyFile options. Members have the
following configuration requirements:
Cluster member configuration must specify a non-empty value for at least one of the attributes used for authentication. By default, MongoDB accepts:
the Organization (
the Organizational Unit (
the Domain Component (
You can specify alternative attributes to use for authentication by setting
Cluster member configuration must include the same
net.tls.clusterAuthX509.attributesand use matching values. Attribute order doesn't matter. The following example sets
OU, but not
net: tls: clusterAuthX509: attributes: O=MongoDB, OU=MongoDB Server
The certificates have the following requirements:
A single Certificate Authority (CA) must issue all x.509 certificates for the members of a sharded cluster or a replica set.
At least one of the Subject Alternative Name (
SAN) entries must match the server hostname used by other cluster members. When comparing
SANs, MongoDB can compare either DNS names or IP addresses.
If you don't specify
subjectAltName, MongoDB compares the Common Name (CN) instead. However, this usage of CN is deprecated per RFC2818
If the certificate used as the
extendedKeyUsage, the value must include both
clientAuth("TLS Web Client Authentication") and
serverAuth("TLS Web Server Authentication").
extendedKeyUsage = clientAuth, serverAuth
If the certificate used as the
extendedKeyUsage, the value must include
extendedKeyUsage = clientAuth
To use TLS for internal authentication, use the following settings:
mongos instances use their certificate key files to
prove their identity to clients, but certificate key files can also be used for
membership authentication. If you do not specify a cluster file,
members use their certificate key files for membership authentication.
Specify the certificate key file with
(available starting in MongoDB 4.2).
To use the certificate key file for both client authentication and membership authentication, the certificate must either:
extendedKeyUsage = serverAuth, clientAuth