- Security >
- Authentication >
- Authentication Mechanisms >
- x.509 >
- Use x.509 Certificates to Authenticate Clients
Use x.509 Certificates to Authenticate Clients¶
On this page
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.
See also
To use x.509 authentication for the internal authentication of replica set/sharded cluster members, 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.
Warning
If the --sslCAFile
option and its target
file are not specified, x.509 client and member authentication will not
function. mongod
, and mongos
in sharded systems,
will not be able to verify the certificates of processes connecting to it
against the trusted certificate authority (CA) that issued them, breaking
the certificate chain.
As of version 2.6.4, mongod
will not start with x.509
authentication enabled if the CA file is not specified.
Client x.509 Certificate¶
Note
You must have valid x.509 certificates.
Starting in MongoDB 3.6.6, if you specify
--sslAllowInvalidCertificates
or ssl.allowInvalidCertificates:
true
when using x.509 authentication, an invalid certificate is
only sufficient to establish a TLS/SSL connection but is
insufficient for authentication.
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:
Each unique MongoDB user must have a unique certificate.
A client x.509 certificate’s subject, which contains the Distinguished Name (
DN
), must differ from that of a Member x.509 Certificate. Specifically, the subjects must differ with regards to at least one of the following attributes: Organization (O
), the Organizational Unit (OU
) or the Domain Component (DC
).Warning
If a client x.509 certificate’s subject has the same
O
,OU
, andDC
combination as the Member x.509 Certificate, the client will be identified as a cluster member and granted full permission on the system.
MongoDB Deployment Configured for x.509¶
- Command-Options
- Configuration File
You can configure mongod
/mongos
for x.509 authentication from the command-line. For example,
if running a replica set, each member would include the
following options:
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 |
---|---|
--clusterAuthMode . |
If the deployment is a replica set or a sharded cluster, specify Omit for standalone. |
--sslMode |
Specify requireSSL . |
--sslPEMKeyFile |
The instance’s x.509 certificate. |
--sslCAFile |
Certificate Authority file to verify the certificate presented to the instance. |
You can configure mongod
/mongos
for x.509 authentication in the configuration file. For example, if running
a replica set, each member would include the following
options:
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 |
---|---|
security.clusterAuthMode |
If the deployment is a replica set or a sharded cluster, specify Omit for standalone. |
net.ssl.mode |
Specify requireSSL . |
net.ssl.PEMKeyFile |
The instance’s x.509 certificate. |
net.ssl.CAFile |
Certificate Authority file to verify the certificate presented to the instance. |
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:The command returns the
subject
string as well as 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:
See Manage Users and Roles for details on adding a user with roles.
Authenticate with a x.509 Certificate¶
After you have added the x.509 client certificate subject as a corresponding MongoDB user, you can authenticate with the client certificate.
- Connect with Authentication
- Authenticate after Connection
To authenticate during connection:
Option | Notes |
---|---|
--ssl |
|
--sslPEMKeyFile |
Client’s x.509 file. |
--sslCAFile |
Certificate Authority file to verify the
certificate presented by
mongod /mongos
instance. |
--authenticationDatabase |
Specify '$external' . |
--authenticationMechanism |
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:Option Notes --ssl
--sslPEMKeyFile
Client’s x.509 file. --sslCAFile
Certificate Authority file to verify the certificate presented by mongod
/mongos
instance.To perform the authentication, use the
db.auth()
method in the$external
database. For themechanism
field, specify"MONGODB-X509"
.