- Security >
- Authentication >
- Authentication Mechanisms >
- x.509 >
- Use x.509 Certificates to Authenticate Clients
Use x.509 Certificates to Authenticate Clients¶
On this page
New in version 2.6.
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.
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 single certificate authority. You or your organization can generate and maintain an independent certificate authority, or use certificates generated by a third-party TLS/SSL vendor. Obtaining and managing certificates is beyond the scope of this documentation.
Client x.509 Certificate¶
Note
You must have valid x.509 certificates.
Starting in MongoDB 3.2.21, 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.
Procedures¶
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
and mongos
instances.
Note
If you are configuring a standalone mongod
, omit the
--clusterAuthMode
option.
Use Command-line Options¶
You can configure the MongoDB server from the command line, e.g.:
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.
Use Configuration File¶
You may also specify these options in the configuration file.
Starting in MongoDB 2.6, you can specify the configuration for MongoDB in YAML format, e.g.:
For backwards compatibility, you can also specify the configuration using the older configuration file format, e.g.:
Include any additional options, TLS/SSL or otherwise, that are required for your specific configuration.
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. 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.
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, in the
mongo
shell, to add the user with both thereadWrite
role in thetest
database and theuserAdminAnyDatabase
role which is defined only in theadmin
database:In the above example, to add the user with the
readWrite
role in thetest
database, the role specification document specified'test'
in thedb
field. To adduserAdminAnyDatabase
role for the user, the above example specified'admin'
in thedb
field.Note
Some roles are defined only in the
admin
database, including:clusterAdmin
,readAnyDatabase
,readWriteAnyDatabase
,dbAdminAnyDatabase
, anduserAdminAnyDatabase
. To add a user with these roles, specify'admin'
in thedb
.
See Manage Users and Roles for details on adding a user with roles.
Authenticate with a x.509 Certificate¶
To authenticate with a client certificate, you must first add a MongoDB user that corresponds to the client certificate. See Add x.509 Certificate subject as a User.
To authenticate, use the db.auth()
method in the
$external
database, specifying "MONGODB-X509"
for the
mechanism
field, and the user that corresponds to the client
certificate for the user
field.
For example, if using the mongo
shell,