Docs Menu
Docs Home
/
MongoDB Manual
/
Self-Managed Deployments
/
Security
/
Authentication
/
Internal

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

On this page

  • About This Task
  • Steps
  • Set override parameter on all members.
  • Restart all members.
  • Modify configuration of all members.
  • Restart all members.
  • Remove override parameter from all members.
  • Restart all members.

Members of a replica set or a sharded cluster 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 doesn't use the net.tls.clusterAuthX509 settings to configure Distinguished Name (DN) attributes.

Note

To perform a rolling update to rotate certificates on a cluster that uses the net.tls.clusterAuthX509 settings or on a cluster that will use these settings after the update, see Rotate x.509 Certificates with clusterAuthX509 Attributes on Self-Managed Clusters.

When a server node receives a connection request, it compares the Distinguished Name (DN) attributes in the subject field of the presented certificates to the subject DN attributes of its own certificates. The certificates match if their subjects contain the same values for the Organization (O), Organizational Unit (OU), and Domain Component (DC) attributes. A server's configuration file can also specify alternative DN attributes to use for matching in the tlsX509ClusterAuthDNOverride parameter. If the server's subject DN attributes or configured tlsX509ClusterAuthDNOverride value match the subject DN attributes of the presented certificate, the server node treats the connection as a cluster member.

In some situations, you may need to update the member certificates to new certificates with new subject Distinguished Name (DN) attributes, 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 tlsX509ClusterAuthDNOverride 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 each member's x.509 certificates, set using the clusterFile and certificateKeyFile settings, have subject DN attributes of "OU=10gen Server,O=10gen".

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

net.tls.mode: requireTLS
net.tls.certificateKeyFile: "./mycerts/10gen-server1.pem"
net.tls.CAFile: "./mycerts/ca.pem"
security.clusterAuthMode: x509
net.tls.clusterFile:  "./mycerts/10gen-cluster1.pem"
net.tls.clusterCAFile: "./mycerts/ca.pem"

The following procedure updates each member's certificates to new certificates that have subject DN attributes of "OU=MongoDB Server, O=MongoDB".

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

1

Set override parameter on all members.

During a rolling update, members are restarted one at a time with a new configuration. To allow server nodes with the the old subject DN attributes to identify nodes with the new subject DN attributes as cluster members, set the override parameter to the new subject DN attributes on all running members.

To do this, modify the configuration file of each server to set the tlsX509ClusterAuthDNOverride parameter to use the subject DN attributes of the new certificate:

net.tls.mode: requireTLS
net.tls.certificateKeyFile: "./mycerts/10gen-server1.pem"
net.tls.CAFile: "./mycerts/ca.pem"
security.clusterAuthMode: x509
net.tls.clusterFile:  "./mycerts/10gen-cluster1.pem"
net.tls.clusterCAFile: "./mycerts/ca.pem"
setParameter:
   tlsX509ClusterAuthDNOverride: "OU=MongoDB Server,O=MongoDB"

This configuration will not be taken into consideration until you restart each member.

2

Restart all members.

To perform a rolling restart of all members, restart each secondary and then the primary.

For each secondary member, connect mongosh to the member, then:

  1. Use the db.shutdownServer() method to shut down the member:

    use admin
    db.shutdownServer()

  2. Restart the member.

    Before restarting the next secondary, ensure this member has reached SECONDARY state. To determine the member state, run rs.status() and read the value of the stateStr field.

    rs.status().members

For the primary member, connect mongosh to the member, then:

  1. Use rs.stepDown() to step down the member:

    rs.stepDown()

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

    use admin
    db.shutdownServer()

  3. Restart the member.

All servers in the replica set can now use the override parameter to accept peer connections from members using certificates with the new subject DN attributes.

3

Modify configuration of all members.

Update the configuration file of each server:

For example:

net.tls.mode: requireTLS
net.tls.certificateKeyFile: "./mycerts/mongodb-server1.pem"
net.tls.CAFile: "./mycerts/ca.pem"
security.clusterAuthMode: x509
net.tls.clusterFile:  "./mycerts/mongodb-cluster1.pem"
net.tls.clusterCAFile: "./mycerts/ca.pem"
setParameter:
   tlsX509ClusterAuthDNOverride: "OU=10Gen Server,O=10Gen"

This configuration will not be taken into consideration until you restart each member.

4

Restart all members.

To apply the updated configuration to each member, perform a rolling restart of the server nodes by repeating the procedure from step 2.

During this process, nodes that have been restarted with new certificates will use the old DN attributes stored in tlsX509ClusterAuthDNOverride to identify nodes presenting old certificates. Nodes that still have old certificates will use the new DN stored in tlsX509ClusterAuthDNOverride to identify nodes presenting new certificates.

5

Remove override parameter from all members.

To prevent the updated server nodes from treating clients presenting the old certificate as peers, remove the tlsX509ClusterAuthDNOverride parameter from all server node configuration files.

For example:

net.tls.mode: requireTLS
net.tls.certificateKeyFile: "./mycerts/mongodb-server1.pem"
net.tls.CAFile: "./mycerts/ca.pem"
security.clusterAuthMode: x509
net.tls.clusterFile:  "./mycerts/mongodb-cluster1.pem"
net.tls.clusterCAFile: "./mycerts/ca.pem"

This configuration will not be taken into consideration until you restart each member.

6

Restart all members.

To apply the updated configuration to each member, perform a rolling restart of the server nodes by repeating the procedure from step 2.

All servers in the replica set now accept peer connections only from members using certificates that have the new subject DN attributes.

Back

Upgrade to x.509 from Keyfile

Next

Rotate x.509 with New clusterAuthX509 Attributes