Rotate X.509 Certificates to Use Extension Values

On this page

About This Task

Steps
Learn More

This version of the documentation is archived and no longer supported. View the current documentation to learn how to upgrade your version of MongoDB server.

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 the attributes setting with the the extensionValue 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 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 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 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 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 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:
       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 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 Cluster Certificates

Localhost Exception