- Security >
- Security Tutorials >
- Access Control Tutorials >
- Use x.509 Certificate for Membership Authentication
Use x.509 Certificate for Membership Authentication¶
On this page
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.
For client authentication with x.509, see Use x.509 Certificates to Authenticate Clients.
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.
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’ssubject
, must specify a non-empty value for at least one of the following attributes: Organization (O
), the Organizational Unit (OU
) or the Domain Component (DC
).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 forO
,OU
as well as the non-specification of theDC
attribute.However, the following two
DN
’s contain a mismatch for theOU
attribute since one contains twoOU
specifications 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:
You can use an x509 certificate that does not have Extended Key
Usage (EKU) attributes set. If you use EKU attribute in the
PEMKeyFile
certificate, then specify the
clientAuth
and/or serverAuth
attributes (i.e. “TLS Web Client
Authentication” and “TLS Web Server Authentication,”) as needed. The
certificate that you specify for the PEMKeyFile
option requires the serverAuth
attribute, and the certificate you
specify to clusterFile
requires the clientAuth
attribute. If you omit ClusterFile
, mongod
will use the certificate specified to PEMKeyFile
for
member authentication.
Configure Replica Set/Sharded Cluster¶
Use Command-line Options¶
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:
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.
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 can specify the configuration for MongoDB in a YAML formatted configuration file, as in the following example:
See security.clusterAuthMode
, net.ssl.mode
,
net.ssl.PEMKeyFile
, net.ssl.CAFile
, and
net.ssl.clusterFile
for more information on the settings.
Upgrade from Keyfile Authentication to x.509 Authentication¶
To upgrade clusters that are currently using keyfile authentication to x.509 authentication, use a rolling upgrade process.
Clusters Currently Using TLS/SSL¶
For clusters using TLS/SSL and keyfile authentication, to upgrade to x.509 cluster authentication, use the following rolling upgrade process:
For each node of a cluster, start the node with the option
--clusterAuthMode
set tosendKeyFile
and the option--sslClusterFile
set to the appropriate path of the node’s certificate. Include other TLS/SSL options as well as any other options that are required for your specific configuration. For example:With this setting, each node continues to use its keyfile to authenticate itself as a member. However, each node can now accept either a keyfile or an x.509 certificate from other members to authenticate those members. Upgrade all nodes of the cluster to this setting.
Then, for each node of a cluster, connect to the node and use the
setParameter
command to update theclusterAuthMode
tosendX509
. [1] For example,With this setting, each node uses its x.509 certificate, specified with the
--sslClusterFile
option in the previous step, to authenticate itself as a member. However, each node continues to accept either a keyfile or an x.509 certificate from other members to authenticate those members. Upgrade all nodes of the cluster to this setting.Optional but recommended. Finally, for each node of the cluster, connect to the node and use the
setParameter
command to update theclusterAuthMode
tox509
to only use the x.509 certificate for authentication. [1] For example:After the upgrade of all nodes, edit the configuration file with the appropriate x.509 settings to ensure that upon subsequent restarts, the cluster uses x.509 authentication.
See mongod --clusterAuthMode
and mongos
--clusterAuthMode
for the various modes and their descriptions.
Clusters Currently Not Using TLS/SSL¶
For clusters using keyfile authentication but not TLS/SSL, to upgrade to x.509 authentication, use the following rolling upgrade process:
For each node of a cluster, start the node with the option
--sslMode
set toallowSSL
, the option--clusterAuthMode
set tosendKeyFile
and the option--sslClusterFile
set to the appropriate path of the node’s certificate. Include other TLS/SSL options as well as any other options that are required for your specific configuration. For example:The :
--sslMode allowSSL
setting allows the node to accept both TLS/SSL and non-TLS/non-SSL incoming connections. Its outgoing connections do not use TLS/SSL.The
--clusterAuthMode sendKeyFile
setting allows each node continues to use its keyfile to authenticate itself as a member. However, each node can now accept either a keyfile or an x.509 certificate from other members to authenticate those members.Upgrade all nodes of the cluster to these settings.
Then, for each node of a cluster, connect to the node and use the
setParameter
command to update thesslMode
topreferSSL
and theclusterAuthMode
tosendX509
. [1] For example:With the
sslMode
set topreferSSL
, the node accepts both TLS/SSL and non-TLS/non-SSL incoming connections, and its outgoing connections use TLS/SSL.With the
clusterAuthMode
set tosendX509
, each node uses its x.509 certificate, specified with the--sslClusterFile
option in the previous step, to authenticate itself as a member. However, each node continues to accept either a keyfile or an x.509 certificate from other members to authenticate those members.Upgrade all nodes of the cluster to these settings.
Optional but recommended. Finally, for each node of the cluster, connect to the node and use the
setParameter
command to update thesslMode
torequireSSL
and theclusterAuthMode
tox509
. [1] For example:With the
sslMode
set torequireSSL
, the node only uses TLS/SSLs connections.With the
clusterAuthMode
set tox509
, the node only uses the x.509 certificate for authentication.After the upgrade of all nodes, edit the configuration file with the appropriate TLS/SSL and x.509 settings to ensure that upon subsequent restarts, the cluster uses x.509 authentication.
See mongod --clusterAuthMode
and mongos
--clusterAuthMode
for the various modes and their descriptions.
[1] | (1, 2, 3, 4) As an alternative to using the
setParameter command, you can also
restart the nodes with the appropriate TLS/SSL and x509 options and
values. |