Use x.509 Certificate for Membership Authentication¶
New in version 2.6.
MongoDB supports x.509 certificate authentication for use with a secure TLS/SSL connection. Sharded cluster members and replica set members can use x.509 certificates to verify their membership to the cluster or the replica set instead of using keyfiles. The membership authentication is an internal process.
Enabling internal authentication also enables Role-Based Access Control. Clients must authenticate as a user in order to connect and perform operations in the deployment.
- See the Manage Users and Roles tutorial for instructions on adding users to the deployment.
- See the Use x.509 Certificates to Authenticate Clients tutorial for instructions on using x.509 certificates for user authentication.
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.
Member x.509 Certificate¶
The member certificate, used for internal authentication to verify membership to the sharded cluster or a replica set, must have the following properties:
A single Certificate Authority (CA) must issue all the x.509 certificates for the members of a sharded cluster or a replica set.
The Distinguished Name (
DN), found in the member certificate’s
subject, must specify a non-empty value for at least one of the following attributes: Organization (
O), the Organizational Unit (
OU) or the Domain Component (
The Organization attributes (
O‘s), the Organizational Unit attributes (
OU‘s), and the Domain Components (
DC‘s) must match those from the certificates for the other cluster members. To match, the certificate must match all specifications of these attributes, or even the non-specification of these attributes. The order of the attributes does not matter.
In the following example, the two
DN‘s contain matching specifications for
OUas well as the non-specification of the
CN=host1,OU=Dept1,O=MongoDB,ST=NY,C=US C=US, ST=CA, O=MongoDB, OU=Dept1, CN=host2
However, the following two
DN‘s contain a mismatch for the
OUattribute since one contains two
OUspecifications and the other, only one specification.
Either the Common Name (
CN) or one of the Subject Alternative Name (
SAN) entries must match the hostname of the server, used by the other members of the cluster.
For example, the certificates for a cluster could have the following subjects:
subject= CN=<myhostname1>,OU=Dept1,O=MongoDB,ST=NY,C=US subject= CN=<myhostname2>,OU=Dept1,O=MongoDB,ST=NY,C=US subject= CN=<myhostname3>,OU=Dept1,O=MongoDB,ST=NY,C=US
If the certificate includes the Extended Key Usage (
extendedKeyUsage) setting, the value must include
clientAuth(“TLS Web Client Authentication”).
extendedKeyUsage = clientAuth
You can also use a certificate that does not include the Extended Key Usage (EKU).
Member Certificate and
To configure MongoDB for client certificate authentication, the
mongos specify a
prove its identity to clients, either through
net.ssl.PEMKeyFile setting in the configuration file or
--sslPEMKeyFile command line option.
clusterFile certificate is specified for
internal member authentication, MongoDB will attempt to use the
PEMKeyFile certificate for member authentication. In order to use
PEMKeyFile certificate for internal authentication as well as for
client authentication, then the
certificate must either:
extendedKeyUsagevalues that include
clientAuthin addition to
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.
Use Command-line Options¶
To specify the x.509 certificate for internal cluster member
authentication, append the additional TLS/SSL options
--sslClusterFile, as in the
following example for a member of a replica set:
mongod --replSet <name> --sslMode requireSSL --clusterAuthMode x509 --sslClusterFile <path to membership certificate and key PEM file> --sslPEMKeyFile <path to SSL certificate and key PEM file> --sslCAFile <path to root CA PEM file>
Include any additional options, TLS/SSL or otherwise, that are required for
your specific configuration. For instance, if the membership key is
encrypted, set the
--sslClusterPassword to the passphrase to
decrypt the key or have MongoDB prompt for the passphrase. See
SSL Certificate Passphrase for details.
--sslCAFile option and its target
file are not specified, x.509 client and member authentication will not
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 can specify the configuration for MongoDB in a YAML formatted configuration file, as in the following example:
security: clusterAuthMode: x509 net: ssl: mode: requireSSL PEMKeyFile: <path to TLS/SSL certificate and key PEM file> CAFile: <path to root CA PEM file> clusterFile: <path to x.509 membership certificate and key PEM file>
To upgrade from keyfile internal authentication to x.509 internal authentication, see Upgrade from Keyfile Authentication to x.509 Authentication.