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.
NoteMongoDB disables support for TLS 1.0 encryption on systems where TLS 1.1+ is available.
Enabling internal authentication also enables Role-Based Access Control in Self-Managed Deployments. Clients must authenticate as a user in order to connect and perform operations in the deployment.
See the Manage Users and Roles on Self-Managed Deployments tutorial for instructions on adding users to the deployment.
See the Use X.509 Certificates to Authenticate Clients on Self-Managed Deployments 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.
NoteYou must have valid X.509 certificates.
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.
When TLS is enabled, use member certificates to verify membership to internal connections in a sharded cluster or a replica set. You can configure member certificate file paths with the net.tls.clusterFile and net.tls.certificateKeyFile options. Members have the following configuration requirements:
Cluster member configuration must specify a non-empty value for at least one of the attributes used for authentication. By default, MongoDB accepts:
the Organization (O)
the Organizational Unit (OU)
the Domain Component (DC)
MongoDB verifies that entries match exactly across all member certificates. If you list multiple OU values, all certificates must use an identical list.
You can specify alternative attributes to use for authentication by setting net.tls.clusterAuthX509.extensionValue.
Cluster member configuration must include the same net.tls.clusterAuthX509.attributes and use matching values. Attribute order doesn't matter. The following example sets O and OU, but not DC:
net: tls: clusterAuthX509: attributes: O=MongoDB, OU=MongoDB ServerIf you set the enforceUserClusterSeparation parameter to false, the following behaviors apply:
You cannot set clusterAuthMode to an option that allows X.509 or the server will not start. The server will only start if clusterAuthMode is keyFile.
A client can create a user in the $external database whose O/OU/DC attributes match the server's configured attributes for cluster membership.
A client presenting a member certificate can now attempt MONGODB-X509 authentication as a user in the $external database.
To set the enforceUserClusterSeparation parameter to false, run the following command during startup:
mongod --setParameter enforceUserClusterSeparation=falseThe certificates have the following requirements:
A single Certificate Authority (CA) must issue all X.509 certificates for the members of a sharded cluster or a replica set.
At least one of the Subject Alternative Name (SAN) entries must match the server hostname used by other cluster members. When comparing SANs, MongoDB can compare either DNS names or IP addresses.
If you don't specify subjectAltName, MongoDB compares the Common Name (CN) instead. However, this usage of CN is deprecated per RFC2818
If the certificate used as the certificateKeyFile includes extendedKeyUsage, the value must include both clientAuth ("TLS Web Client Authentication") and serverAuth ("TLS Web Server Authentication").
extendedKeyUsage = clientAuth, serverAuthIf the certificate used as the clusterFile includes extendedKeyUsage, the value must include clientAuth.
extendedKeyUsage = clientAuthOutside 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 or mongos instances.
mongod and mongos bind to localhost by default. If the members of your deployment are run on different hosts or if you wish remote clients to connect to your deployment, you must specify --bind_ip or net.bindIp.
The procedures in this section use the tls settings/option. For procedures using the deprecated ssl aliases, see Use Command-line Options (ssl).
The tls settings/options provide identical functionality as the ssl options since MongoDB has always supported TLS 1.0 and later.
mongod --replSet <name> --tlsMode requireTLS --clusterAuthMode x509 --tlsClusterFile <path to membership certificate and key PEM file> --tlsCertificateKeyFile <path to TLS/SSL certificate and key file> --tlsCAFile <path to root CA file> --bind_ip localhost,<hostname(s)|ip address(es)>To use X.509 authentication, --tlsCAFile or net.tls.CAFile must be specified unless you are using --tlsCertificateSelector or --net.tls.certificateSelector.
Include any additional options, TLS/SSL or otherwise, that are required for your specific configuration. For
security: clusterAuthMode: x509net: tls: mode: requireTLS certificateKeyFile: <path to its TLS/SSL certificate and key file> CAFile: <path to root CA PEM file to verify received certificate> clusterFile: <path to its certificate key file for membership authentication> bindIp: localhost,<hostname(s)|ip address(es)>To use X.509 authentication, --tlsCAFile or net.tls.CAFile must be specified unless you are using --tlsCertificateSelector or --net.tls.certificateSelector.
Include any additional options, TLS/SSL or otherwise, that are required for your specific configuration.
For more information, see Configure mongod and mongos for TLS/SSL.
The procedures in this section use the deprecated ssl settings/option. For procedures that use tls aliases, see Use Command-line Options (tls).
The tls settings/options provide identical functionality as the ssl options since MongoDB has always supported TLS 1.0 and later.
To specify the X.509 certificate for internal cluster member authentication, append the additional TLS/SSL options --clusterAuthMode and --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 TLS/SSL certificate and key PEM file> --sslCAFile <path to root CA PEM file> --bind_ip localhost,<hostname(s)|ip address(es)>To use X.509 authentication, --tlsCAFile or net.tls.CAFile must be specified unless you are using --tlsCertificateSelector or --net.tls.certificateSelector.
Include any additional options, TLS/SSL or otherwise, that are required for your specific configuration.
security: clusterAuthMode: x509net: 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> bindIp: localhost,<hostname(s)|ip address(es)>To use X.509 authentication, --tlsCAFile or net.tls.CAFile must be specified unless you are using --tlsCertificateSelector or --net.tls.certificateSelector.
Include any additional options, TLS/SSL or otherwise, that are required for your specific configuration.
For more information, see Configure mongod and mongos for TLS/SSL.
To upgrade from keyfile internal authentication to X.509 internal authentication, see Upgrade Self-Managed MongoDB from Keyfile Authentication to X.509 Authentication.
To perform a rolling update of the certificates to new certificates with different DN, see Rotate X.509 Certificates without clusterAuthX509 Attributes on Self-Managed Clusters.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4