- Security >
- Security Tutorials >
- Access Control Tutorials >
- 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 SSL vendor. Obtaining and managing certificates is beyond the scope of this documentation.
Client x.509 Certificate¶
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 MongoDB Server¶
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.
You can retrieve the
subject
from the client certificate with the following command:The command returns the
subject
string as well as certificate:Add the value of the
subject
, omitting the spaces, from the certificate as a user.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 Add a User to a Database 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,