Configure TLS on Self-Managed Deployments

Create a keyfile

Each node uses the contents of a keyfile to authenticate other members of the deployment. Create a keyfile using the following command:

openssl rand -base64 756 > /etc/ssl/mongodb/keyfile
chmod 400 /etc/ssl/mongodb/keyfile

Copy the keyfile to each node in your deployment. Ensure that you restrict permissions on the keyfile so that only the mongod process can read the file.

Edit the configuration file on each node

On each node, locate and open your mongod configuration file. If the file does not exist, create it. Add the following TLS options. Use absolute paths to the certificate files.

For example, the configuration file for your primary node looks like the following:

net:
  tls:
    mode: allowTLS
    certificateKeyFile: /etc/ssl/mongodb/mongo0.pem
    CAFile: /etc/ssl/mongodb/ca.pem
    allowConnectionsWithoutCertificates: true
security:
  clusterAuthMode: keyFile
  keyFile: /etc/ssl/mongodb/keyfile
setParameter:
  tlsWithholdClientCertificate: true

• mode set to allowTLS accepts TLS connections but does not require them, so nodes can complete a rolling restart without interrupting replication.

• certificateKeyFile specifies the node's certificate. Replace the filename with the certificate key file for the specific node you are configuring. CAFile specifies the CA certificate that signed the node's certificate.

• allowConnectionsWithoutCertificates allows clients to connect without providing a TLS certificate.

• clusterAuthMode set to keyFile enables nodes to authenticate using a keyfile. keyFile specifies the keyfile that nodes use to authenticate to each other.

• tlsWithholdClientCertificate prevents the node from presenting its server certificate when making outbound connections to other nodes in the cluster. This is necessary because it prevents nodes from using server-authentication certificates for client authentication, especially if your certificates do not include the clientAuth EKU.

Restart the replica set members

Restart the mongod process to apply the new TLS configuration. To apply the configuration without downtime, restart nodes in a rolling fashion.

On each host for your deployment, starting with the secondary nodes and finishing with the primary node, run the following:

sudo systemctl restart mongod

To verify that the rolling restart completed successfully, run the following command on each host:

sudo systemctl status mongod

Update the configuration to enforce TLS

After all nodes restart successfully with TLS enabled, update the configuration file on each node. Change net.tls.mode from allowTLS to requireTLS to enforce encrypted connections for all clients and members:

net:
  tls:
    mode: requireTLS

Restart the replica set members

Restart the mongod process to apply the new TLS configuration. To apply the configuration without downtime, restart nodes in a rolling fashion.

On each host for your deployment, starting with the secondary nodes and finishing with the primary node, run the following:

sudo systemctl restart mongod

To verify that the rolling restart completed successfully, run the following command on each host:

sudo systemctl status mongod

Edit the configuration file on each node

On each node, locate and open your mongod configuration file. If the file does not exist, create it. Add the following TLS options. Use absolute paths to the certificate files.

For example, the configuration file for your primary node looks like the following:

net:
  tls:
    mode: allowTLS
    certificateKeyFile: /etc/ssl/mongodb/mongo0.pem
    CAFile: /etc/ssl/mongodb/ca.pem
    allowConnectionsWithoutCertificates: true
    clusterAuthX509:
      attributes: O=MongoDB
security:
  clusterAuthMode: x509

• mode set to allowTLS accepts TLS connections but does not require them, so nodes can complete a rolling restart without interrupting replication.

• certificateKeyFile specifies the node's certificate. Replace the filename with the certificate key file for the specific node you are configuring. CAFile specifies the CA certificate that signed the node's certificate.

• allowConnectionsWithoutCertificates allows clients to connect without providing a TLS certificate.

• net.tls.clusterAuthX509.attributes specifies the X.509 certificate attributes that identify a node as a cluster member, rather than a regular client. For required certificate attributes, see Member X.509 Certificate.

• clusterAuthMode set to x509 enables nodes to authenticate using X.509 certificates.

Restart the replica set members

Restart the mongod process to apply the new TLS configuration. To apply the configuration without downtime, restart nodes in a rolling fashion.

On each host for your deployment, starting with the secondary nodes and finishing with the primary node, run the following:

sudo systemctl restart mongod

To verify that the rolling restart completed successfully, run the following command on each host:

sudo systemctl status mongod

Update the configuration to enforce TLS

After all nodes restart successfully with TLS enabled, update the configuration file on each node. Change net.tls.mode from allowTLS to requireTLS to enforce encrypted connections for all clients and members:

net:
  tls:
    mode: requireTLS

Restart the replica set members

Restart the mongod process to apply the new TLS configuration. To apply the configuration without downtime, restart nodes in a rolling fashion.

On each host for your deployment, starting with the secondary nodes and finishing with the primary node, run the following:

sudo systemctl restart mongod

To verify that the rolling restart completed successfully, run the following command on each host:

sudo systemctl status mongod

Inspect logs to verify your TLS configuration

After the rolling restart completes, inspect the logs on each node to verify that TLS is configured correctly. Your logs must include the following content to verify that mTLS and X.509 authentication are correctly configured:

"msg":"Successfully authenticated",
"attr": {
  "isClusterMember":true,
  "mechanism":"MONGODB-X509",
  "user":"CN=mongo1.example.com,O=MongoDB,L=New York City,ST=New-York,C=US"
}

You should see a similar log message for each of the other two nodes in your replica set. For example, if you look at the logs on mongo0, you should see messages similar to the above for mongo1 and mongo2.