Use x.509 Certificate for Membership Authentication
MongoDB supports x.509 certificate authentication for use with a secure TLS/SSL connection. Sharded cluster members and replica set members can use x.509 certificates to verify their membership to the cluster or the replica set instead of using keyfiles. The membership authentication is an internal process.
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.
Enabling internal authentication also enables Role-Based Access Control. Clients must authenticate as a user in order to connect and perform operations in the deployment.
See the Manage Users and Roles tutorial for instructions on adding users to the deployment.
See the Use x.509 Certificates to Authenticate Clients tutorial for instructions on using x.509 certificates for user authentication.
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.
Member x.509 Certificate
Note
You must have valid x.509 certificates.
Starting in MongoDB 4.2, if you specify
--tlsAllowInvalidateCertificates
or
net.tls.allowInvalidCertificates: true
when using x.509
authentication, an invalid certificate is only sufficient to
establish a TLS connection but it is insufficient for
authentication.
Certificate Requirements
Member certificates which you use to verify membership to a sharded
cluster or a replica set (net.tls.clusterFile
, if
specified, and net.tls.certificateKeyFile
), 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:the Organization (
O
)the Organizational Unit (
OU
)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, 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 includes the Extended Key Usage (
extendedKeyUsage
) setting, the value must includeclientAuth
("TLS Web Client Authentication").extendedKeyUsage = clientAuth 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.
Configure Replica Set/Sharded Cluster
Outside of rolling upgrade procedures, every component of a replica set or sharded cluster should use the same
--clusterAuthMode
setting to ensure it can securely connect to all
other components in the deployment.
For replica set deployments, this includes all mongod
members of the replica set.
For sharded cluster deployments, this includes all mongod
or mongos
instances.
Note
Starting in MongoDB 3.6, mongod
and mongos
bind to localhost by default. If the members of your deployment are
run on different hosts or if you wish remote clients to connect to
your deployment, you must specify --bind_ip
or
net.bindIp
. For more information, see
Localhost Binding Compatibility Changes.
Use Command-line Options (tls
)
Note
The procedures in this section use the tls
settings/option. For
procedures using the deprecated ssl
aliases, see
Use Command-line Options (ssl
).
The tls
settings/options provide identical functionality
as the ssl
options since MongoDB has always supported TLS 1.0
and later.
For more information, see Configure mongod
and mongos
for TLS/SSL.
Use Command-line Options (ssl
)
Note
The procedures in this section use the deprecated ssl
settings/option.
For procedures using their tls
aliases (available in MongoDB 4.2+),
see Use Command-line Options (tls
).
The tls
settings/options provide identical functionality
as the ssl
options since MongoDB has always supported TLS 1.0
and later.
For more information, see Configure mongod
and mongos
for TLS/SSL.
Additional Information
To upgrade from keyfile internal authentication to x.509 internal authentication, see Upgrade from Keyfile Authentication to x.509 Authentication.
To perform a rolling update of the certificates to new certificates
with different DN
, see
Rolling Update of x.509 Cluster Certificates that Contain New DN.