- Security >
- Security Tutorials >
- Network Security Tutorials >
- TLS/SSL Configuration for Clients
TLS/SSL Configuration for Clients¶
On this page
Clients must have support for TLS/SSL to work with a mongod
or a
mongos
instance that has TLS/SSL support enabled. The current
versions of the Python, Java, Ruby, Node.js, .NET, and C++ drivers have
support for TLS/SSL, with full support coming in future releases of other
drivers.
Important
A full description of TLS/SSL, PKI (Public Key Infrastructure) certificates, and Certificate Authority is beyond the scope of this document. This page assumes prior knowledge of TLS/SSL as well as access to valid certificates.
Note
Although TLS is the successor to SSL, this page uses the more familiar term SSL to refer to TLS/SSL.
See also
mongo
Shell SSL Configuration¶
For SSL connections, you must use the mongo
shell built with
SSL support or distributed with MongoDB Enterprise. To support SSL,
mongo
has the following settings:
--sslPEMKeyFile
with the name of the.pem
file that contains the SSL certificate and key.--sslCAFile
with the name of the.pem
file that contains the certificate from the Certificate Authority (CA).Warning
If the
mongo
shell or any other tool that connects tomongos
ormongod
is run without--sslCAFile
, it will not attempt to validate server certificates. This results in vulnerability to expiredmongod
andmongos
certificates as well as to foreign processes posing as validmongod
ormongos
instances. Ensure that you always specify the CA file against which server certificates should be validated in cases where intrusion is a possibility.--sslPEMKeyPassword
option if the client certificate-key file is encrypted.
Connect to MongoDB Instance with SSL Encryption¶
To connect to a mongod
or mongos
instance that
requires only a SSL encryption mode,
start mongo
shell with --ssl
, as in
the following:
Connect to MongoDB Instance that Requires Client Certificates¶
To connect to a mongod
or mongos
that requires
CA-signed client certificates, start the mongo
shell with
--ssl
and the --sslPEMKeyFile
option to specify the signed certificate-key file, as
in the following:
Connect to MongoDB Instance that Validates when Presented with a Certificate¶
To connect to a mongod
or mongos
instance that
only requires valid certificates when the client presents a certificate, start mongo
shell either
with the --ssl
ssl and no certificate or
with the --ssl
ssl and a valid signed
certificate.
For example, if mongod
is running with weak certificate
validation, both of the following mongo
shell clients can
connect to that mongod
:
Important
If the client presents a certificate, the certificate must be valid.
MongoDB Cloud Manager¶
The MongoDB Cloud Manager Monitoring agent will also have to connect via SSL in order to gather its statistics. Because the agent already utilizes SSL for its communications to the MongoDB Cloud Manager servers, this is just a matter of enabling SSL support in MongoDB Cloud Manager itself on a per host basis.
See the MongoDB Cloud Manager documentation for more information about SSL configuration.
PyMongo¶
Add the “ssl=True
” parameter to a PyMongo
MongoClient
to create a MongoDB connection to an SSL MongoDB instance:
To connect to a replica set, use the following operation:
PyMongo also supports an “ssl=true
” option for the MongoDB URI
:
For more details, see the Python MongoDB Driver page.
Java¶
Consider the following example “SSLApp.java
” class file:
For more details, see the Java MongoDB Driver page.
Ruby¶
The recent versions of the Ruby driver have support for connections to SSL servers. Install the latest version of the driver with the following command:
Then connect to a standalone instance, using the following form:
Replace connection
with the following if you’re connecting to a
replica set:
Here, mongod
instance run on “localhost:27017
” and
“localhost:27018
”.
For more details, see the Ruby MongoDB Driver page.
Node.JS (node-mongodb-native
)¶
In the node-mongodb-native driver, use the following invocation to
connect to a mongod
or mongos
instance via SSL:
To connect to a replica set via SSL, use the following form:
For more details, see the Node.JS MongoDB Driver page.
.NET¶
As of release 1.6, the .NET driver supports SSL connections with
mongod
and mongos
instances. To connect using
SSL, you must add an option to the connection string, specifying
ssl=true
as follows:
The .NET driver will validate the certificate against the local
trusted certificate store, in addition to providing encryption of the
server. This behavior may produce issues during testing if the server
uses a self-signed certificate. If you encounter this issue, add the
sslverifycertificate=false
option to the connection string to
prevent the .NET driver from validating the certificate, as follows:
For more details, see the .NET MongoDB Driver page.
MongoDB Tools¶
Changed in version 2.6.
Various MongoDB utility programs supports SSL. These tools include:
To use SSL connections with these tools, use the same SSL options as the
mongo
shell. See mongo Shell SSL Configuration.