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.
You can configure a mongod
instance
for x.509 authentication from the command-line. For example,
to configure a standalone mongod
instance:
mongod --tlsMode requireTLS --tlsCertificateKeyFile <path to TLS/SSL certificate and key PEM file> --tlsCAFile <path to root CA PEM file> --bind_ip <hostnames>
Include additional options as required for your configuration. For
instance, if you wish remote clients to connect to your deployment
or your deployment members are run on different hosts, specify the
--bind_ip
. For more information, see
Localhost Binding Compatibility Changes.
The x.509 configuration requires:
Option | Notes |
---|---|
Specify requireTLS . | |
The instance's x.509 certificate to present to clients. | |
Certificate Authority file to verify the certificates
presented to the instance. |
You can configure mongod
for x.509
authentication in the configuration file. For example, to
configure a standalone mongod
instance:
net: tls: mode: requireTLS certificateKeyFile: <path to TLS/SSL certificate and key PEM file> CAFile: <path to root CA PEM file>
Include additional options as required
for your configuration. For instance, if you wish remote clients to
connect to your deployment or your deployment members are run on
different hosts, specify the net.bindIp
setting. For more
information, see Localhost Binding Compatibility Changes.
The x.509 configuration requires:
Option | Notes |
---|---|
Specify requireTLS . | |
The instance's x.509 certificate. | |
Certificate Authority file to verify the certificates
presented to the instance. |
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.
You can configure a mongod
instance
for x.509 authentication from the command-line. For example,
to configure a standalone mongod
instance:
mongod --sslMode requireSSL --sslPEMKeyFile <path to TLS/SSL certificate and key PEM file> --sslCAFile <path to root CA PEM file> --bind_ip <hostnames>
Include additional options as required for your configuration. For
instance, if you wish remote clients to connect to your deployment
or your deployment members are run on different hosts, specify the
--bind_ip
. For more information, see
Localhost Binding Compatibility Changes.
The x.509 configuration for a standalone requires:
Option | Notes |
---|---|
Specify requireSSL . | |
The instance's x.509 certificate. | |
Certificate Authority file to verify the certificate
presented to the instance. |
You can configure mongod
for x.509 authentication in the configuration file. For example,
to configure a standalone mongod
instance:
net: ssl: mode: requireSSL PEMKeyFile: <path to TLS/SSL certificate and key PEM file> CAFile: <path to root CA PEM file>
Include additional options as required
for your configuration. For instance, if you wish remote clients to
connect to your deployment or your deployment members are run on
different hosts, specify the net.bindIp
setting. For more
information, see Localhost Binding Compatibility Changes.
The x.509 configuration for a standalone requires:
Option | Notes |
---|---|
Specify requireSSL . | |
The instance's x.509 certificate. | |
Certificate Authority file to verify the certificate
presented to the instance. |
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.
To authenticate during connection:
mongo --tls --tlsCertificateKeyFile <path to client PEM file> --tlsCAFile <path to root CA PEM file> --authenticationDatabase '$external' --authenticationMechanism MONGODB-X509
Option | Notes |
---|---|
Client's x.509 file. | |
Certificate Authority file to verify the
certificate presented by the
mongod
instance. | |
Specify '$external' . | |
Specify MONGODB-X509 . |
You can connect without authentication and use the
db.auth()
method to authenticate after
connection.
For example, if using the mongo
shell,
Connect
mongo
shell to themongod
set up for TLS/SSL:mongo --tls --tlsCertificateKeyFile <path to client PEM file> --tlsCAFile <path to root CA PEM file> OptionNotesClient's x.509 file.To perform the authentication, use the
db.auth()
method in the$external
database. For themechanism
field, specify"MONGODB-X509"
.db.getSiblingDB("$external").auth( { mechanism: "MONGODB-X509" } )
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.
To authenticate during connection:
mongo --ssl --sslPEMKeyFile <path to CA signed client PEM file> --sslCAFile <path to root CA PEM file> --authenticationDatabase '$external' --authenticationMechanism MONGODB-X509
Option | Notes |
---|---|
Client's x.509 file. | |
Specify '$external' . | |
Specify MONGODB-X509 . |
You can connect without authentication and use the
db.auth()
method to authenticate after
connection.
For example, if using the mongo
shell,
Connect
mongo
shell to themongod
set up for TLS/SSL:mongo --ssl --sslPEMKeyFile <path to CA signed client PEM file> --sslCAFile <path to root CA PEM file> OptionNotesClient's x.509 file.To perform the authentication, use the
db.auth()
method in the$external
database. For themechanism
field, specify"MONGODB-X509"
.db.getSiblingDB("$external").auth( { mechanism: "MONGODB-X509" } )