Docs Menu

Docs HomeDevelop ApplicationsMongoDB 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.

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.

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.

1

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 }
2

Restart each secondary cluster member:

  1. Use mongosh to connect to each secondary cluster member, then use the db.shutdownServer() method to stop the server:

    use admin
    db.shutdownServer()
  2. Restart the server.

  3. Use the rs.status() method to determine the member state:

    rs.status().members
  4. 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.

3

Restart the primary member:

  1. 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.

  2. Use the db.shutdownServer() method to shut the server down:

    use admin
    db.shutdownServer()
  3. 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.

4

Update the configuration file of each server:

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 }
5

Restart each secondary cluster member:

  1. Use mongosh to connect to each secondary cluster member, then use the db.shutdownServer() method to stop the server:

    use admin
    db.shutdownServer()
  2. Restart the server.

  3. Use the rs.status() method to determine the member state:

    rs.status().members
  4. 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.

6

Restart the primary member:

  1. 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.

  2. Use the db.shutdownServer() method to shut the server down:

    use admin
    db.shutdownServer()
  3. Restart the server.

The primary server in the replica set steps down and restarts as a secondary that uses the new X.509 certificate.

7

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.

8

Restart each secondary cluster member:

  1. Use mongosh to connect to each secondary cluster member, then use the db.shutdownServer() method to stop the server:

    use admin
    db.shutdownServer()
  2. Restart the server.

  3. Use the rs.status() method to determine the member state:

    rs.status().members
  4. 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.

9

Restart the primary member:

  1. 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.

  2. Use the db.shutdownServer() method to shut the server down:

    use admin
    db.shutdownServer()
  3. Restart the server.

The primary server steps down and restarts as a secondary that no longer accepts connections from the old X.509 certificates.

←  Rolling Update of x.509 Cluster Certificates that Contain New DNRotate X.509 Certificates to Use Extension Values →