Pymongo and SSL/TLS Connection to MongoDB

Secure Sockets Layer (SSL) and its successor, Transport Layer Security (TLS), are cryptographic protocols designed to provide communication security over a computer network. When it comes to databases like MongoDB, using SSL/TLS is essential to ensure that the data transmitted between the database and the client remains confidential and secure from potential eavesdroppers.

SSL/TLS works by establishing a secure connection between two parties through a series of steps known as the handshake process. During this handshake, the client and server authenticate each other using digital certificates, and they negotiate the encryption algorithms and keys to be used. It is crucial to understand that while SSL is still widely referenced, the industry has largely transitioned to TLS, which offers enhanced security features.

When configuring MongoDB for SSL/TLS, it’s important to first ensure that the MongoDB server is set up to support SSL connections. This typically involves generating SSL certificates and configuring the MongoDB server to use them. The certificates can either be self-signed or signed by a trusted Certificate Authority (CA).

Here’s a basic outline of how to generate a self-signed certificate for use with MongoDB:

openssl genrsa -out mongodb.pem 2048
openssl req -new -x509 -key mongodb.pem -out mongodb.pem -days 365 -subj "/CN=localhost"

After generating the certificate, you will need to modify the MongoDB configuration file (usually named mongod.conf) to enable SSL. You would typically include settings such as the path to your certificate and the mode of SSL operation. An example configuration snippet might look like this:

net:
  ssl:
    mode: requireSSL
    PEMKeyFile: /path/to/mongodb.pem

Once the server is configured, the next step is to ensure that the connections from your applications to the MongoDB instance are also secured using SSL/TLS. This is where the client libraries, like PyMongo, come into play. PyMongo provides options to specify SSL settings when establishing connections, ensuring that your data remains encrypted during transmission.

Understanding these foundational elements of SSL/TLS is essential before diving into the specific configurations needed in your application code. The importance of ensuring that both the server and client sides are correctly set up cannot be overstated, as any misconfiguration can lead to vulnerabilities that undermine the security of your data.

Apple Watch Series 11 [GPS 42mm] Smartwatch with Rose Gold Aluminum Case with Light Blush Sport Band - S/M. Sleep Score, Fitness Tracker, Health Monitoring, Always-On Display, Water Resistant

(485930)

25% Off $399.00 $299.00 (as of December 9, 2025 08:28 GMT +00:00 - More infoProduct prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on [relevant Amazon Site(s), as applicable] at the time of purchase will apply to the purchase of this product.)

HYPERTENSION NOTIFICATIONS — Apple Watch Series 11 can spot signs of chronic high blood pressure and notify you of possible hypertension.* KNOW YOUR SLEEP SCORE — Sleep score provides an easy way to help track and understand the quality of your sleep... read more

Configuring Pymongo to establish an encrypted SSL TLS session

Configuring PyMongo to connect to a MongoDB instance over an SSL/TLS-secured channel involves specifying relevant parameters when creating the MongoClient. At the minimum, you need to enable SSL itself by setting tls=True (or the older ssl=True), and optionally provide paths to the Certificate Authority (CA) certificate to validate the server’s certificate.

Here is a simpler example that shows how to connect to a MongoDB server on localhost with SSL enabled, but without client certificate authentication:

from pymongo import MongoClient

client = MongoClient(
    "mongodb://localhost:27017/",
    tls=True,
    tlsAllowInvalidCertificates=False
)

db = client.test_database
print(db.list_collection_names())

In this snippet, tls=True tells PyMongo to use TLS for the connection. Setting tlsAllowInvalidCertificates=False enforces strict validation of the server’s certificate, which especially important in production environments. Without this, PyMongo will accept self-signed or invalid certificates, negating the benefit of TLS.

If the MongoDB server is using a self-signed certificate or one signed by a private CA, your client will need the corresponding CA certificate to properly validate the server’s identity. You provide this using the tlsCAFile parameter:

client = MongoClient(
    "mongodb://mongodb.example.com:27017/",
    tls=True,
    tlsCAFile="/path/to/ca.pem"
)

This ca.pem file should contain the trusted root certificate that was used to sign the server’s SSL certificate. Without it, PyMongo will reject the connection if strict validation is enforced.

For cases where client-side authentication is required (mutual TLS), additional parameters are necessary. You must supply the client certificate plus the corresponding private key. Often these are combined in a single PEM file, but PyMongo can accept separate files:

client = MongoClient(
    "mongodb://mongodb.example.com:27017/",
    tls=True,
    tlsCAFile="/path/to/ca.pem",
    tlsCertificateKeyFile="/path/to/client.pem"
)

In the above, client.pem contains both the client’s certificate and private key in PEM format. PyMongo uses this certificate to authenticate the client during the handshake process.

If your private key is encrypted with a password or passphrase, PyMongo allows you to supply it via tlsCertificateKeyFilePassword:

client = MongoClient(
    "mongodb://mongodb.example.com:27017/",
    tls=True,
    tlsCAFile="/path/to/ca.pem",
    tlsCertificateKeyFile="/path/to/client.pem",
    tlsCertificateKeyFilePassword="your_password"
)

Connection strings can also directly embed SSL/TLS options as query parameters. The same example with mutual TLS could be expressed as:

conn_str = (
    "mongodb://mongodb.example.com:27017/?"
    "tls=true&"
    "tlsCAFile=/path/to/ca.pem&"
    "tlsCertificateKeyFile=/path/to/client.pem"
)

client = MongoClient(conn_str)

It’s worth noting that earlier PyMongo versions used parameters like ssl=true, ssl_ca_certs, and ssl_certfile. These are deprecated in favor of tls-prefixed options for clarity and consistency.

Beyond these basics, you can fine-tune several other TLS parameters such as cipher suites, certificate revocation checks, or TLS versions allowed, through options like tlsAllowInvalidHostnames or tlsInsecure—although these should be used with caution as they weaken security.

Here is an extended sample showing a more robust connection approach:

client = MongoClient(
    "mongodb://mongodb.example.com:27017/",
    tls=True,
    tlsCAFile="/path/to/ca.pem",
    tlsCertificateKeyFile="/path/to/client.pem",
    tlsCertificateKeyFilePassword="your_password",
    tlsAllowInvalidHostnames=False
)

This setup ensures the client validates the server’s hostname against the certificate and requires a valid client cert. These checks are fundamental to preventing man-in-the-middle attacks.