Rotate x.509 Certificates with clusterAuthX509 Attributes on Self-Managed Clusters

On this page

About This Task

Steps
Learn More

New in version 7.0.

Cluster members can use x.509 certificates for membership authentication to identify other servers in the same deployment. This tutorial describes how to perform a rolling update to rotate x.509 certificates on a cluster that uses the net.tls.clusterAuthX509.attributes settings to configure the cluster members' Distinguished Name (DN) attributes.

Note

To perform a rolling update to rotate certificates on a cluster that doesn't use the net.tls.clusterAuthX509 settings and won't after the update, see Rotate x.509 Certificates without clusterAuthX509 Attributes on Self-Managed Clusters.

When a server configured with the net.tls.clusterAuthX509.attributes setting receives a connection request, it compares the Distinguished Name (DN) attributes in the subject field of the presented certificates to the configured values of the attributes setting and tlsClusterAuthX509Override parameter. If the values match, it treats the connection as a cluster member.

In some situations, you may need to update the member certificates to new certificates with a new Distinguished Name (DN), such as if an organization changes its name. In a rolling update, member certificates are updated one at a time, and your deployment does not incur any downtime.

Clusters adopting new certificates can use the tlsClusterAuthX509Override parameter to accept x.509 certificates with different subject DN attributes 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) attributes that use the 10gen organization and 10gen Server organizational unit. These DN attributes are set using the net.tls.clusterAuthX509.attributes setting.

A member of this replica set has the following configuration file:

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=10gen, OU=10gen Server

The following procedure updates each replica set member's x.509 certificates to new certificates that have DN attributes that use the MongoDB organization and MongoDB Server organizational unit.

Note

The following procedure assumes that the new x.509 certificates meet membership certificate and all other requirements and that the cluster configuration identifies peer certificates using Distinguished Name (DN) values. For more information, see Member Certificate Requirements.

Steps

These steps update member certificates to use new x.509 certificates on a cluster configured with the net.tls.clusterAuthX509.attributes setting.

The new certificates have Distinguished Names (DN) that change the Organization (O) attributes from 10gen to MongoDB and the Organizational Unit (OU) attribute from 10gen Server to MongoDB Server.

Update the TLS Cluster Membership Configuration

Update the configuration file of each server:

Change attributes setting to use the values on the new certificate
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:
       attributes:      O=MongoDB, OU=MongoDB Server
security:
  clusterAuthMode: x509
setParameter:
   tlsClusterAuthX509Override: { attributes: O=10gen, OU=10gen Server }

Restart Secondary Cluster Members

Restart each secondary cluster member:

Use mongosh to connect to each secondary cluster member, then use the db.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 of SECONDARY, then restart the next secondary.

Secondary servers in the replica set now accept peer connections from members using certificates with the new DN attributes.

Restart Primary Cluster Member

Restart the primary member:

Connect to the primary using mongosh, then use the rs.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 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:
       attributes:      O=MongoDB, OU=MongoDB Server
security:
  clusterAuthMode: x509
setParameter:
   tlsClusterAuthX509Override: { attributes: O=10gen, OU=10gen Server }

Restart Secondary Cluster Members

Restart each secondary cluster member:

Use mongosh to connect to each secondary cluster member, then use the db.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 of SECONDARY, 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 the rs.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:
       attributes:      O=MongoDB, OU=MongoDB Server
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 the db.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 of SECONDARY, 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 the rs.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.

Learn More

Back

Rotate x.509 with New DN

Rotate x.509 to Use Extension Values