Use x.509 Certificates to Authenticate Clients on Self-Managed Deployments
On this page
The following procedure sets up x.509 certificate authentication for
client authentication on a standalone mongod
instance.
To use x.509 authentication for replica sets or sharded clusters, see Use x.509 Certificate for Membership Authentication with Self-Managed MongoDB.
Prerequisites
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 vendors. Obtaining and managing certificates is beyond the scope of this documentation.
To use x.509 authentication, --tlsCAFile
or net.tls.CAFile
must be specified unless you are using --tlsCertificateSelector
or --net.tls.certificateSelector
.
Client x.509 Certificate
You must have valid x.509 certificates. The client x.509 certificates must meet the client certificate requirements.
If you specify --tlsAllowInvalidCertificates
or
net.tls.allowInvalidCertificates: true
, an invalid certificate is
sufficient only to establish a TLS connection but it is
insufficient for authentication.
Procedure
Deploy with x.509 Authentication
You can configure a mongod
instance for x.509
authentication from the command-line.
To configure a standalone mongod
instance, run
the following command:
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.
The x.509 configuration requires:
Option | Notes |
---|---|
Specify requireTLS . | |
Specify the instance's x.509 certificate to present to
clients. | |
Specify the Certificate Authority file to verify the
certificates presented to the instance. |
You can configure a mongod
for x.509
authentication in the configuration file.
To configure a standalone mongod
instance, add
the following configuration options to your configuration
file:
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.
The x.509 configuration requires:
Option | Notes |
---|---|
Specify requireTLS . | |
Specify the instance's x.509 certificate to present to
clients. | |
Specify the 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 with Self-Managed MongoDB.
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. You cannot use a single client
certificate to authenticate more than one MongoDB user.
Note
Username Requirements
To use Client Sessions and Causal Consistency Guarantees with
$external
authentication users (Kerberos, LDAP, or x.509 users), usernames cannot be greater than 10k bytes.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 and the 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.The following example 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 on Self-Managed Deployments 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:
To authenticate during connection, run the following command:
mongosh --tls --tlsCertificateKeyFile <path to client PEM file> \ --tlsCAFile <path to root CA PEM file> \ --authenticationDatabase '$external' \ --authenticationMechanism MONGODB-X509
Option | Notes |
---|---|
Specify the client's x.509 file. | |
Specify the 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 mongosh
,
Connect
mongosh
to themongod
:mongosh --tls --tlsCertificateKeyFile <path to client PEM file> \ --tlsCAFile <path to root CA PEM file> OptionNotesSpecify the client's x.509 file.To authenticate, use the
db.auth()
method in the$external
database. For themechanism
field, specify"MONGODB-X509"
.db.getSiblingDB("$external").auth( { mechanism: "MONGODB-X509" } )
Next Steps
To use x.509 authentication for replica sets or sharded clusters, see Use x.509 Certificate for Membership Authentication with Self-Managed MongoDB.