Rotate X.509 Certificates to Use Extension Values on Self-Managed Clusters
On this page
New in version 7.0.
Cluster members can use X.509 certificates for membership authentication to identify other servers in the same deployment.
When the server receives a connection request, it compares the
Distinguished Name (DN) values or the extension value string
of the certificate to the configured values of the
clusterAuthX509
setting and
tlsClusterAuthX509Override
parameter.
If the values match, it treats the connection as a cluster member.
Clusters adopting new certificates can use the
tlsClusterAuthX509Override
parameter to migrate from
certificates identified using DN attributes to certificates identified
using extension values during the certificate rotation procedure.
Once all members use certificates with the new value, remove the override to begin rejecting the now out of date certificates.
About This Task
Consider a replica set where member certificates
(set using the clusterFile
and
certificateKeyFile
settings)
have Distinguished Name (DN) values that use the MongoDB
organization
and MongoDB Server
organizational unit (set using the
attributes
setting).
security: clusterAuthMode: x509 net: tls: mode: requireTLS certificateKeyFile: /etc/mycerts/10gen-server1.pem CAFile: /etc/mycerts/ca.pem clusterFile: /etc/mycerts/10gen-cluster1.pem clusterCAFile: /etc/mycerts/ca.pem clusterAuthX509: attributes: O=MongoDB, OU=MongoDB Server
This tutorial assumes that the new X.509 certificates meet membership certificate and all other requirements and that the cluster configuration identifies peer certificates using extension values.
For details, see Member Certificate Requirements.
Steps
These steps update member certificates to use new X.509 certificates
on a cluster configured with the
attributes
setting.
Initially, the clusters identify members using DN values.
With the new certificates, the servers instead identify members
using the mongodb://example.mongodb.net
extension value and ignore certificate attributes.
Update the TLS Cluster Membership Configuration
Update the configuration file of each server:
Change the
clusterAuthX509
setting to match the new certificate by replacing theattributes
setting with the theextensionValue
setting.Set the
tlsClusterAuthX509Override
parameter to use the DN attributes of the old certificate.
For example:
net: tls: mode: requireTLS certificateKeyFile: /etc/mycerts/mongodb-server1.pem CAFile: /etc/mycerts/ca.pem clusterFile: /etc/mycerts/mongodb-cluster1.pem clusterCAFile: /etc/mycerts/ca.pem clusterAuthX509: extensionValue: mongodb://example.mongodb.net security: clusterAuthMode: x509 setParameter: tlsClusterAuthX509Override: { attributes: O=MongoDB, OU=MongoDBServer }
Restart Secondary Cluster Members
Restart each secondary cluster member:
Use
mongosh
to connect to each secondary cluster member, then use thedb.shutdownServer()
method to stop the server:use admin db.shutdownServer() Restart the server.
Use the
rs.status()
method to determine the member state:rs.status().members Wait for the
stateStr
field for this member to show a value ofSECONDARY
, then restart the next secondary.
Secondary servers in the replica set now accept peer connections from members using certificates with the new extension values as well as the old DN attributes.
Restart Primary Cluster Member
Restart the primary member:
Connect to the primary using
mongosh
, then use thers.stepDown()
method to step the member down as the primary:rs.stepDown() The cluster promotes a secondary with the new certificate to serve as the new primary.
Use the
db.shutdownServer()
method to shut the server down:use admin db.shutdownServer() Restart the server.
The primary server in the replica set steps down and restarts as a secondary that now accepts peer connections from members using certificates with the new extension value as well as the old DN attributes.
Update the TLS Certificates
Update the configuration file of each server:
Change the
net.tls.certificateKeyFile
setting to use the new certificate.Change the
net.tls.clusterFile
setting to use the new certificate.
For example:
net: tls: mode: requireTLS certificateKeyFile: /etc/mycerts/mongodb-server2.pem CAFile: /etc/mycerts/ca.pem clusterFile: /etc/mycerts/mongodb-cluster2.pem clusterCAFile: /etc/mycerts/ca.pem clusterAuthX509: extensionValue: mongodb://example.mongodb.net security: clusterAuthMode: x509 setParameter: tlsClusterAuthX509Override: { attributes: O=MongoDB, OU=MongoDB Server }
Restart Secondary Cluster Members
Restart each secondary cluster member:
Use
mongosh
to connect to each secondary cluster member, then use thedb.shutdownServer()
method to stop the server:use admin db.shutdownServer() Restart the server.
Use the
rs.status()
method to determine the member state:rs.status().members Wait for the
stateStr
field for this member to show a value ofSECONDARY
, then restart the next secondary.
Secondary servers in the replica set now use the new X.509 certificates.
Restart Primary Cluster Member
Restart the primary member:
Connect to the primary using
mongosh
, then use thers.stepDown()
method to step the member down as the primary:rs.stepDown() The cluster promotes a secondary with the new certificate to serve as the new primary.
Use the
db.shutdownServer()
method to shut the server down:use admin db.shutdownServer() Restart the server.
The primary server in the replica set steps down and restarts as a secondary that uses the new X.509 certificate.
Remove the DN Certification Override Configuration
With all members of the cluster now using the new X.509 certificate,
update the configuration file to remove the setParameter
settings for the tlsClusterAuthX509Override
parameter.
For example:
net: tls: mode: requireTLS certificateKeyFile: /etc/mycerts/mongodb-server1.pem CAFile: /etc/mycerts/ca.pem clusterFile: /etc/mycerts/mongodb-cluster1.pem clusterCAFile: /etc/mycerts/ca.pem clusterAuthX509: extensionValue: mongodb://example.mongodb.net security: clusterAuthMode: x509
This ensures that the server doesn't configure the old certificate settings on startup.
Restart Secondary Cluster Members
Restart each secondary cluster member:
Use
mongosh
to connect to each secondary cluster member, then use thedb.shutdownServer()
method to stop the server:use admin db.shutdownServer() Restart the server.
Use the
rs.status()
method to determine the member state:rs.status().members Wait for the
stateStr
field for this member to show a value ofSECONDARY
, then restart the next secondary.
Secondary servers in the replica set restart and no longer accept connections from the old X.509 certificates.
Restart Primary Cluster Member
Restart the primary member:
Connect to the primary using
mongosh
, then use thers.stepDown()
method to step the member down as the primary:rs.stepDown() The cluster promotes a secondary with the new certificate to serve as the new primary.
Use the
db.shutdownServer()
method to shut the server down:use admin db.shutdownServer() Restart the server.
The primary server steps down and restarts as a secondary that no longer accepts connections from the old X.509 certificates.