Use x.509 Certificates to Authenticate Clients
On this page
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.
MongoDB supports x.509 certificate authentication for use with a secure
TLS/SSL connection. The x.509 client
authentication allows clients to authenticate to servers with
certificates rather than with a username
and password. The following tutorial outlines the steps to use x.509
for client authentication with a standalone mongod
instance.
To use x.509 authentication for replica sets or sharded clusters, see Use x.509 Certificate for Membership Authentication.
Prerequisites
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.
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.
Important
To use x.509 authentication, --tlsCAFile
or net.tls.CAFile
must be specified unless using --tlsCertificateSelector
or
--net.tls.certificateSelector
. Or if using the ssl
aliases,
--sslCAFile
or net.ssl.CAFile
must be specified unless using
--sslCertificateSelector
or net.ssl.certificateSelector
.
Client x.509 Certificate
Note
You must have valid x.509 certificates.
Starting in MongoDB 4.0, if you specify any of the following x.509 authentication options, an invalid certificate is sufficient only to establish a TLS connection but it is insufficient for authentication:
--sslAllowInvalidCertificates
ornet.ssl.allowInvalidCertificates: true
for MongoDB 4.0 and later--tlsAllowInvalidCertificates
ornet.tls.allowInvalidCertificates: true
for MongoDB 4.2 and later
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 Deployment Configured for x.509 (Using TLS Options)
Note
The procedures in this section use the tls
settings/option
(Available in MongoDB 4.2). For procedures using their ssl
aliases, see MongoDB Deployment Configured for x.509 (Using SSL Options).
The tls
settings/options provide identical functionality
as the ssl
options since MongoDB has always supported TLS 1.0
and later.
To set up x.509 authentication for replica sets or sharded clusters, see Use x.509 Certificate for Membership Authentication.
MongoDB Deployment Configured for x.509 (Using SSL Options)
Note
The procedures in this section use the ssl
settings/option. For
procedures using their tls
aliases (Available in MongoDB 4.2),
see MongoDB Deployment Configured for x.509 (Using TLS Options).
The tls
settings/options provide identical functionality
as the ssl
options since MongoDB has always supported TLS 1.0
and later.
To set up x.509 authentication for replica sets or sharded clusters, see Use x.509 Certificate for Membership Authentication.
Procedures
Add x.509 Certificate subject
as a User
To authenticate with a client certificate, you must first add the value
of the subject
from the client certificate as a MongoDB user to the
$external
database. 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.
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.
Note
The RDNs in the subject
string must be compatible with the
RFC2253 standard.
You can retrieve the
RFC2253
formattedsubject
from the client certificate with the following command:openssl x509 -in <pathToClientPEM> -inform PEM -subject -nameopt RFC2253 The command returns the
subject
string as well as certificate:subject= CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry -----BEGIN CERTIFICATE----- # ... -----END CERTIFICATE----- Add the
RFC2253
compliant value of thesubject
as a user. Omit spaces as needed.For example, the following adds a user and grants the user
readWrite
role in thetest
database and theuserAdminAnyDatabase
role:db.getSiblingDB("$external").runCommand( { createUser: "CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry", roles: [ { role: "readWrite", db: "test" }, { role: "userAdminAnyDatabase", db: "admin" } ], writeConcern: { w: "majority" , wtimeout: 5000 } } )
See Manage Users and Roles for details on adding a user with roles.
Authenticate with a x.509 Certificate (Using tls
Options)
Note
The procedures in this section use the tls
settings/option
(Available in MongoDB 4.2). For procedures using their ssl
aliases, see Authenticate with a x.509 Certificate (Using ssl
Options).
The tls
settings/options provide identical functionality
as the ssl
options since MongoDB has always supported TLS 1.0
and later.
After you have added the x.509 client certificate subject as a corresponding MongoDB user, you can authenticate with the client certificate.
Authenticate with a x.509 Certificate (Using ssl
Options)
Note
The procedures in this section use the ssl
settings/options. For
procedures using their tls
(Available in MongoDB 4.2) aliases,
see Authenticate with a x.509 Certificate (Using tls
Options).
The tls
settings/options provide identical functionality
as the ssl
options since MongoDB has always supported TLS 1.0
and later.
After you have added the x.509 client certificate subject as a corresponding MongoDB user, you can authenticate with the client certificate.