TLS/SSL and PyMongo

For connections using TLS/SSL, PyMongo may require third party dependencies asdetermined by your version of Python. With PyMongo 3.3+, you can installPyMongo 3.3+ and any TLS/SSL-related dependencies using the following pipcommand:

Earlier versions of PyMongo require you to manually install the dependencieslisted below.

The module is required on all platforms.

When using CPython < 2.7.9 or PyPy < 2.5.1:

On Windows, the wincertstore module is required.
On all other platforms, the module is required.

Warning

Industry best practices recommend, and some regulations require,the use of TLS 1.1 or newer. Though no application changes are required forPyMongo to make use of the newest protocols, some operating systems orversions may not provide an OpenSSL version new enough to support them.

Users of macOS older than 10.13 (High Sierra) will need to install Pythonfrom python.org, , macports, or another similar source.

Users of Linux or other non-macOS Unix can check their OpenSSL version likethis:

$ openssl version

If the version number is less than 1.0.1 support for TLS 1.1 or newer is notavailable. Contact your operating system vendor for a solution or upgrade toa newer distribution.

python -c "import requests; print(requests.get('https://www.howsmyssl.com/a/check', verify=False).json()['tls_version'])"

You should see “TLS 1.X” where X is >= 1.

You can read more about TLS versions and their security implications here:

Basic configuration

In many cases connecting to MongoDB over TLS/SSL requires nothing more thanpassing as a keyword argument to:

>>> client = pymongo.MongoClient('example.com', ssl=True)

Or passing in the URI:

This configures PyMongo to connect to the server using TLS, verify the server’scertificate and verify that the host you are attempting to connect to is listedby that certificate.

By default, PyMongo is configured to require a certificate from the server whenTLS is enabled. This is configurable using the ssl_cert_reqs option. Todisable this requirement pass as a keyword parameter:

>>> import ssl
>>> client = pymongo.MongoClient('example.com',
...                              ssl=True,
...                              ssl_cert_reqs=ssl.CERT_NONE)

Or, in the URI:

Specifying a CA file

In some cases you may want to configure PyMongo to use a specific set of CAcertificates. This is most often the case when using “self-signed” servercertificates. The ssl_ca_certs option takes a path to a CA file. It can bepassed as a keyword argument:

>>> client = pymongo.MongoClient('example.com',
...                              ssl=True,
...                              ssl_ca_certs='/path/to/ca.pem')

>>> uri = 'mongodb://example.com/?ssl=true&ssl_ca_certs=/path/to/ca.pem'
>>> client = pymongo.MongoClient(uri)

Python 2.7.9+ (pypy 2.5.1+) and 3.4+ provide support for certificate revocationlists. The ssl_crlfile option takes a path to a CRL file. It can be passed asa keyword argument:

>>> client = pymongo.MongoClient('example.com',
...                              ssl=True,
...                              ssl_crlfile='/path/to/crl.pem')

Or, in the URI:

>>> uri = 'mongodb://example.com/?ssl=true&ssl_crlfile=/path/to/crl.pem'

Client certificates

PyMongo can be configured to present a client certificate using thessl_certfile option:

>>> client = pymongo.MongoClient('example.com',
...                              ssl=True,
...                              ssl_certfile='/path/to/client.pem')

If the private key for the client certificate is stored in a separate file usethe ssl_keyfile option:

Python 2.7.9+ (pypy 2.5.1+) and 3.3+ support providing a password or passphraseto decrypt encrypted private keys. Use the ssl_pem_passphrase option:

>>> client = pymongo.MongoClient('example.com',
...                              ssl=True,
...                              ssl_certfile='/path/to/client.pem',
...                              ssl_keyfile='/path/to/key.pem',
...                              ssl_pem_passphrase=<passphrase>)

These options can also be passed as part of the MongoDB URI.

TLS errors often fall into two categories, certificate verification failure orprotocol version mismatch. An error message similar to the following means thatOpenSSL was not able to verify the server’s certificate:

[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed

This often occurs because OpenSSL does not have access to the system’sroot certificates or the certificates are out of date. Linux users shouldensure that they have the latest root certificate updates installed fromtheir Linux vendor. macOS users using Python 3.6.0 or newer downloadedfrom python.org to installroot certificates:

open "/Applications/Python <YOUR PYTHON VERSION>/Install Certificates.command"

Users of older PyPy portable versions may have to set an environmentvariable to tellOpenSSL where to find root certificates. This is easily done using the from pypi:

$ pypy -m pip install certifi
$ export SSL_CERT_FILE=$(pypy -c "import certifi; print(certifi.where())")

[SSL: TLSV1_ALERT_PROTOCOL_VERSION] tlsv1 alert protocol version

Industry best practices recommend, and some regulations require, that olderTLS protocols be disabled in some MongoDB deployments. Some deployments maydisable TLS 1.0, others may disable TLS 1.0 and TLS 1.1. See the warningearlier in this document for troubleshooting steps and solutions.