Docs Home → Develop Applications → MongoDB Manual

Rotate X.509 Cluster Certificates

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.

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 accept X.509 certificates with different 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.

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 Rolling Update of x.509 Cluster Certificates that Contain New DN.

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 10gen organization and 10gen 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=10gen, OU=10gen 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 Distinguished Name (DN) 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.

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

← Rolling Update of x.509 Cluster Certificates that Contain New DN

Rotate X.509 Certificates to Use Extension Values →