Docs Menu
Docs Home
/
MongoDB Manual
/ / /

Rotate X.509 Certificates to Use Extension Values

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

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.

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.

1

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 }
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 extension values as well as the old 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 extension value as well as the old 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:
extensionValue: mongodb://example.mongodb.net
security:
clusterAuthMode: x509
setParameter:
tlsClusterAuthX509Override: { attributes: O=MongoDB, OU=MongoDB 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:
extensionValue: mongodb://example.mongodb.net
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.

Back

Rotate X.509 Cluster Certificates