Docs Home → Develop Applications → MongoDB Manual
x.509![](/docs/v5.3/assets/link.svg)
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.
Certificate Authority![](/docs/v5.3/assets/link.svg)
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.
Client x.509 Certificates![](/docs/v5.3/assets/link.svg)
To authenticate to servers, clients can use x.509 certificates instead of usernames and passwords.
Client Certificate Requirements![](/docs/v5.3/assets/link.svg)
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.
Note
Changed in version 4.4:
mongod
/mongos
logs a warning on connection if the presented x.509 certificate expires within30
days of themongod/mongos
host system time. See x.509 Certificates Nearing Expiry Trigger Warnings for more information.Client certificates must contain the following fields:
keyUsage = digitalSignature extendedKeyUsage = clientAuth At least one of the following client certificate attributes must be different than the attributes in both the
net.tls.clusterFile
andnet.tls.certificateKeyFile
server certificates:Organization (
O
)Organizational Unit (
OU
)Domain Component (
DC
)
The
subject
of a client x.509 certificate, which contains the Distinguished Name (DN
), must be different than thesubject
s of member x.509 certificates.Important
If a client x.509 certificate's subject matches the
O
,OU
, andDC
attributes of the Member x.509 Certificate (ortlsX509ClusterAuthDNOverride
, 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
, andDC
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.
MongoDB User and $external
Database![](/docs/v5.3/assets/link.svg)
To authenticate with a client certificate, you must first add the client
certificate's subject
as a MongoDB user in the $external
database.
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.
TLS Connection X509 Certificate Startup Warning![](/docs/v5.3/assets/link.svg)
Starting in MongoDB 5.0, mongod
and mongos
now
issue a startup warning when their certificates do not include a
Subject Alternative Name attribute.
The following platforms do not support common name validation:
iOS 13 and higher
MacOS 10.15 and higher
Go 1.15 and higher
Clients using these platforms will not authenticate to MongoDB servers that use x.509 certificates whose hostnames are specified by CommonName attributes.
Member x.509 Certificates![](/docs/v5.3/assets/link.svg)
For internal authentication between members of sharded clusters and replica sets, you can use x.509 certificates instead of keyfiles.
Member Certificate Requirements![](/docs/v5.3/assets/link.svg)
Use member certificates to verify membership to a sharded
cluster or a replica set. Member certificates are stored in
net.tls.clusterFile
and net.tls.certificateKeyFile
.
Member certificate requirements:
A single Certificate Authority (CA) must issue all x.509 certificates for the members of a sharded cluster or a replica set.
The x.509 certificate must not be expired.
Note
Changed in version 4.4:
mongod
/mongos
logs a warning on connection if the presented x.509 certificate expires within30
days of themongod/mongos
host system time. See x.509 Certificates Nearing Expiry Trigger Warnings for more information.The Distinguished Name (
DN
), found in the member certificate'ssubject
, must specify a non-empty value for at least one of the following attributes:the Organization (
O
)the Organizational Unit (
OU
)the Domain Component (
DC
)
Each cluster member certificate must have identical
O
s,OU
s, andDC
s in theirnet.tls.clusterFile
andnet.tls.certificateKeyFile
certificates. This also applies to thetlsX509ClusterAuthDNOverride
value, if set. Attribute order doesn't matter.Here's an example. The two
DN
s below have matching specifications forO
andOU
, andDC
is not specified.CN=host1,OU=Dept1,O=MongoDB,ST=NY,C=US C=US, ST=CA, O=MongoDB, OU=Dept1, CN=host2 The following example is incorrect, because the
DN
s don't match. OneDN
has twoOU
specifications and the other has only oneOU
specification.CN=host1,OU=Dept1,OU=Sales,O=MongoDB CN=host2,OU=Dept1,O=MongoDB Either the Common Name (
CN
) or one of the Subject Alternative Name (SAN
) entries must match the server hostname for other cluster members. Starting in MongoDB 4.2, when comparingSAN
s, MongoDB can compare either DNS names or IP addresses. In previous versions, MongoDB only compares DNS names.For example, the certificates for a cluster could have the following
subject
s:subject= CN=<myhostname1>,OU=Dept1,O=MongoDB,ST=NY,C=US subject= CN=<myhostname2>,OU=Dept1,O=MongoDB,ST=NY,C=US subject= CN=<myhostname3>,OU=Dept1,O=MongoDB,ST=NY,C=US If the certificate includes the Extended Key Usage (
extendedKeyUsage
) setting, the value must includeclientAuth
("TLS Web Client Authentication").extendedKeyUsage = clientAuth
MongoDB Configuration for Membership Authentication![](/docs/v5.3/assets/link.svg)
You can use TLS for internal authentication between each member of
your replica set (each mongod
instance) or sharded
cluster (each mongod
and mongos
instance).
To use TLS for internal authentication, use the following settings:
security.clusterAuthMode
or--clusterAuthMode
set tox509
net.tls.clusterFile
or--tlsClusterFile
(available starting in MongoDB 4.2)
mongod
and 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 net.tls.certificateKeyFile
or
--tlsCertificateKeyFile
(available starting in MongoDB 4.2).
To use the certificate key file for both client authentication and membership authentication, the certificate must either:
Omit
extendedKeyUsage
orSpecify
extendedKeyUsage = serverAuth, clientAuth