x.509
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.
Note
MongoDB disables support for TLS 1.0 encryption on systems where TLS 1.1+ is available. For more details, see Disable TLS 1.0.
Certificate Authority
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.
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.Warning
If a client x.509 certificate's subject has the same
O
,OU
, andDC
combination as the Member x.509 Certificate (ortlsX509ClusterAuthDNOverride
if set), the client connection is rejected. Only cluster member x509 certificates should use sameO
,OU
, andDC
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 within30
days of themongod/mongos
host system time. See x.509 Certificates Nearing Expiry Trigger Warnings for more information.
MongoDB User and $external
Database
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.
Add the user in the $external
database; i.e. the
Authentication Database is the $external
database
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.
Authenticate
To connect and authenticate using x.509 client certificate:
For MongoDB 4.2 or greater, include the following options for the client:
--tlsCertificateKeyFile
(or the deprecated--sslPEMKeyFile
option)--tlsCertificateKeyFilePassword
(or the deprecated--sslPEMKeyPassword
option) if the certificate key file is encrypted
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 tls
Options)
section in Use x.509 Certificates to Authenticate Clients
TLS Connection X509 Certificate Startup Warning
Starting in MongoDB 4.4.7, 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 which use X.509 certificate whose hostnames are specified by CommonName attributes.
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
The member certificate (net.tls.clusterFile
, if
specified, and net.tls.certificateKeyFile
), used to
verify membership to the sharded cluster or a replica set, must have
the following properties:
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'ssubject
, must specify a non-empty value for at least one of the following attributes: Organization (O
), the Organizational Unit (OU
) or the Domain Component (DC
).The Organization attributes (
O
's), the Organizational Unit attributes (OU
's), and the Domain Components (DC
's) must match those from both thenet.tls.clusterFile
andnet.tls.certificateKeyFile
certificates for the other cluster members (or thetlsX509ClusterAuthDNOverride
value, if set).To match, the certificate must match all specifications of these attributes, or even the non-specification of these attributes. The order of the attributes does not matter.
In the following example, the two
DN
's contain matching specifications forO
,OU
as well as the non-specification of theDC
attribute.CN=host1,OU=Dept1,O=MongoDB,ST=NY,C=US C=US, ST=CA, O=MongoDB, OU=Dept1, CN=host2 However, the following two
DN
's contain a mismatch for theOU
attribute since one contains twoOU
specifications and the other, only one 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 subjects:
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 used as the
certificateKeyFile
includesextendedKeyUsage
, the value must include bothclientAuth
("TLS Web Client Authentication") andserverAuth
("TLS Web Server Authentication").extendedKeyUsage = clientAuth, serverAuth If the certificate used as the
clusterFile
includesextendedKeyUsage
, the value must includeclientAuth
.extendedKeyUsage = clientAuth You can also use a certificate that does not include the Extended Key Usage (EKU).
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 within30
days of themongod/mongos
host system time. See x.509 Certificates Nearing Expiry Trigger Warnings for more information.
MongoDB Configuration for Membership Authentication
In addition to any TLS/SSL configurations as appropriate for your
deployment, include the following to specify x.509 for internal
authentication for each member of your replica set (i.e. the
mongod
instances) or sharded cluster (i.e. the
mongod
and mongos
instances):
security.clusterAuthMode
or--clusterAuthMode
set tox509
net.tls.clusterFile
or--tlsClusterFile
(both new in MongoDB 4.2)
However, if no cluster file is specified, members can use their
certificate key file specified in
net.tls.certificateKeyFile
or
--tlsCertificateKeyFile
(both new in MongoDB 4.2) for membership authentication. This
certificate key file
is used
by mongod
(and mongos
) instances to prove their identity
to clients, but can also be used for membership authentication. To
use for both client authentication and membership authentication,
the certificate must either:
Omit
extendedKeyUsage
orSpecify
extendedKeyUsage
values
Note
Athough still available, net.ssl.clusterFile
(and the
correponding --sslClusterFile
) and net.ssl.PEMKeyFile
(and the
corresponding --sslPEMKeyFile
)
are deprecated as of MongoDB 4.2.
For deployments using MongoDB version 4.0 and earlier, use
net.ssl.clusterFile
(or the corresponding
--sslClusterFile
) and
net.ssl.PEMKeyFile
(or the corresponding
--sslPEMKeyFile
).
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 within30
days of themongod/mongos
host system time. See x.509 Certificates Nearing Expiry Trigger Warnings for more information.
Next Steps
For an example of x.509 internal authentication, see Use x.509 Certificate for Membership Authentication.