Last updated: 2026-06-25

MongoDB TLS Configuration

MongoDB 4.2 replaced the net.ssl configuration block with net.tls. The old net.ssl options were fully removed in MongoDB 8.0; use net.tls throughout. MongoDB 8.0 or later is recommended; 7.0 remains supported.

Certificate Preparation#

MongoDB expects the server 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: mongodb:mongodb

/etc/mongod.conf#

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-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305"
  opensslCipherSuiteConfig: "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256"

Key settings:

• mode: requireTLS - enforces TLS on all connections. Don't use allowTLS or preferTLS in production; both accept plaintext.
• disabledProtocols - explicitly blocks TLS 1.0 and 1.1. Omitting this relies on OpenSSL's defaults, which may still allow them depending on the system configuration.
• allowConnectionsWithoutCertificates: false - requires clients to present a valid certificate (mutual TLS). Default is true.
• opensslCipherConfig - restricts TLS 1.2 cipher selection. Without this, MongoDB inherits OpenSSL's system defaults.
• opensslCipherSuiteConfig - TLS 1.3 cipher suites. Available in MongoDB 5.0+.

See RFC 8446 §4.3.2 for the TLS Certificate Request specification, and Wikipedia: Mutual authentication for a general overview.

Replica Sets#

Each member needs TLS configured. To use x.509 certificates for member-to-member authentication instead of keyfiles:

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 the certificate used for internal authentication between replica set members. If omitted, MongoDB falls back to certificateKeyFile for both client-facing and intra-cluster connections. Setting clusterAuthMode: x509 switches internal auth from keyfiles to certificates.

Client Connections#

mongosh:

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

Connection string format with client certificate:

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

Server-only TLS (no client certificate):

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

Security Notes#

The cipher suite and protocol configuration in this guide addresses the following known TLS vulnerabilities:

• POODLE (CVE-2014-3566, 2014): SSL 3.0 is disabled. TLS_FALLBACK_SCSV was added in OpenSSL 1.0.1j / 1.0.2 (October 2014); SSL 3.0 disabled by default in OpenSSL 1.1.0 (August 2016).
• BEAST (CVE-2011-3389, 2011): Mitigated by recommending TLS 1.2 as the minimum; AEAD-only ciphers eliminate the CBC padding oracle.
• CRIME (CVE-2012-4929, 2012): TLS compression is off by default in OpenSSL 1.1.0+; do not enable it.
• Lucky13 (2013): AEAD-only cipher list eliminates CBC padding timing side-channels entirely.
• FREAK (CVE-2015-0204, 2015): EXPORT-grade ciphers are excluded. Removed from OpenSSL 1.1.0 (August 2016).
• LOGJAM (CVE-2015-4000, 2015): Short-key DHE is excluded; only ECDHE key exchange is recommended.
• Sweet32 (CVE-2016-2183, 2016): 3DES is excluded from the cipher string.
• ROBOT (2017): Static RSA key exchange is excluded; only ECDHE is recommended.
• Downgrade attacks: TLS_FALLBACK_SCSV prevents protocol version rollback.
• Renegotiation injection (CVE-2009-3555, 2009): Secure renegotiation is enforced by default in OpenSSL 0.9.8m+; TLS 1.3 removes renegotiation entirely.

The following are not addressable through TLS configuration alone:

• Heartbleed (CVE-2014-0160, 2014): A memory disclosure bug in OpenSSL 1.0.1 through 1.0.1f. Fixed in OpenSSL 1.0.1g (April 7, 2014). Addressed by patching OpenSSL, not by TLS configuration.
• BREACH (CVE-2013-3587, 2013): Not applicable. BREACH targets HTTP-level response compression; the MongoDB wire protocol does not involve HTTP.
• DROWN (CVE-2016-0800, 2016): Requires SSLv2 to be enabled on any server sharing the same private key. Ensure SSLv2 is disabled on all services that use the same certificate and key pair.

Verification#

systemctl restart mongod

Check the active TLS mode:

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

Test the TLS handshake directly:

openssl s_client -connect mongodb.example.com:27017