Last updated: 2026-02-11

MongoDB TLS/SSL Configuration Guide

This guide provides recommended TLS/SSL settings for MongoDB to encrypt connections between clients, replica set members, and sharded cluster nodes. MongoDB 4.2+ uses the net.tls configuration options (replacing the older net.ssl options, which were fully removed in MongoDB 8.0).

Prerequisites

MongoDB 4.2 or later (for net.tls settings; 4.4+ recommended)
OpenSSL 1.1.1 or later (for TLS 1.3 support)
SSL certificates (server certificate with private key in PEM format, and CA certificate)

MongoDB expects the certificate and private key combined in a single PEM file:

cat /etc/mongodb/ssl/server.crt /etc/mongodb/ssl/server.key > /etc/mongodb/ssl/mongodb.pem
chmod 600 /etc/mongodb/ssl/mongodb.pem
chown mongod:mongod /etc/mongodb/ssl/mongodb.pem   # Debian/Ubuntu: chown mongodb:mongodb

Server Configuration

Add the following settings to your MongoDB configuration file (/etc/mongod.conf), which uses YAML format.

Enable TLS

Set the TLS mode to requireTLS to enforce encryption for all connections:

net:
  tls:
    mode: requireTLS
    certificateKeyFile: /etc/mongodb/ssl/mongodb.pem
    CAFile: /etc/mongodb/ssl/ca.pem

Available TLS modes:

disabled -- No TLS (default)
allowTLS -- Accept both TLS and plaintext connections
preferTLS -- Accept both, but prefer TLS
requireTLS -- Only accept TLS connections (recommended)

Disable Legacy Protocols

Disable TLS 1.0 and TLS 1.1:

net:
  tls:
    disabledProtocols: TLS1_0,TLS1_1

This leaves only TLS 1.2 and TLS 1.3 available.

Cipher Suite Configuration

MongoDB uses OpenSSL's default cipher suite ordering. To restrict to strong ciphers, use the opensslCipherConfig parameter:

setParameter:
  opensslCipherConfig: "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305"

Or pass it as a command-line parameter:

mongod --setParameter opensslCipherConfig="ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305"

For TLS 1.3 cipher suites (MongoDB 5.0+, via opensslCipherSuiteConfig):

setParameter:
  opensslCipherSuiteConfig: "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256"

Client Certificate Validation

To require clients to present a valid certificate (mutual TLS), set allowConnectionsWithoutCertificates to false:

net:
  tls:
    allowConnectionsWithoutCertificates: false

The default is true, which allows clients to connect without presenting a certificate.

Complete Server Configuration

net:
  port: 27017
  tls:
    mode: requireTLS
    certificateKeyFile: /etc/mongodb/ssl/mongodb.pem
    CAFile: /etc/mongodb/ssl/ca.pem
    disabledProtocols: TLS1_0,TLS1_1
    allowConnectionsWithoutCertificates: false

setParameter:
  opensslCipherConfig: "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305"
  # opensslCipherSuiteConfig requires MongoDB 5.0+; omit on 4.2-4.4
  opensslCipherSuiteConfig: "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256"

Replica Set Configuration

For replica set members to communicate over TLS, each member must have TLS configured. Additionally, configure the cluster authentication mode:

net:
  tls:
    mode: requireTLS
    certificateKeyFile: /etc/mongodb/ssl/mongodb.pem
    CAFile: /etc/mongodb/ssl/ca.pem
    clusterFile: /etc/mongodb/ssl/mongodb-cluster.pem
    disabledProtocols: TLS1_0,TLS1_1

security:
  clusterAuthMode: x509

clusterFile is a separate certificate used for internal cluster member authentication (optional; uses certificateKeyFile if not specified).
clusterAuthMode: x509 uses TLS certificates for authenticating replica set members to each other.

Client Connections

mongosh (MongoDB Shell)

Connect with TLS using mongosh (MongoDB 5.0+):

mongosh "mongodb://mongodb.example.com:27017/mydb" --tls --tlsCAFile /etc/mongodb/ssl/ca.pem --tlsCertificateKeyFile /etc/mongodb/ssl/client.pem

On MongoDB 4.2--4.4, the shell is mongo (not mongosh) and uses --ssl flags:

mongo "mongodb://mongodb.example.com:27017/mydb" --ssl --sslCAFile /etc/mongodb/ssl/ca.pem --sslPEMKeyFile /etc/mongodb/ssl/client.pem

Connection String

Use the tls=true parameter in MongoDB connection strings:

mongodb://mongodb.example.com:27017/mydb?tls=true&tlsCAFile=/path/to/ca.pem&tlsCertificateKeyFile=/path/to/client.pem

For applications where you only need to verify the server (no client certificate):

mongodb://mongodb.example.com:27017/mydb?tls=true&tlsCAFile=/path/to/ca.pem

Verification

Restart MongoDB and check the log for TLS status:

systemctl restart mongod

Verify TLS is active:

mongosh --tls --tlsCAFile /etc/mongodb/ssl/ca.pem --eval "db.adminCommand({getParameter: 1, tlsMode: 1})"

Test the TLS connection with OpenSSL:

openssl s_client -connect mongodb.example.com:27017

Check the connection encryption in the shell:

mongosh --tls --tlsCAFile /etc/mongodb/ssl/ca.pem --eval "db.adminCommand({connectionStatus: 1})"