- Security >
- Security Tutorials >
- Network Security Tutorials >
- Connect to MongoDB with SSL
Connect to MongoDB with SSL¶
This document outlines the use and operation of MongoDB’s SSL
support. SSL allows MongoDB clients to support encrypted connections
to mongod
instances.
Note
The default distribution of MongoDB does not contain
support for SSL. To use SSL, you must either build MongoDB locally
passing the “--ssl
” option to scons
or use MongoDB
Enterprise.
These instructions outline the process for getting started with SSL and assume that you have already installed a build of MongoDB that includes SSL support and that your client driver supports SSL.
Important
A full description of SSL, PKI (Public Key Infrastructure) certificates, and Certificate Authority is beyond the scope of this document. This page assumes prior knowledge of SSL as well as access to valid certificates.
Configure mongod
and mongos
for SSL¶
Combine SSL Certificate and Key File¶
Before you can use SSL, you must have a .pem
file that
contains the public key certificate and private key. MongoDB can use
any valid SSL certificate. To generate a self-signed certificate and
private key, use a command that resembles the following:
This operation generates a new, self-signed certificate with no
passphrase that is valid for 365 days. Once you have the certificate,
concatenate the certificate and private key to a .pem
file, as
in the following example:
Set Up mongod
and mongos
with SSL Certificate and Key¶
To use SSL in your MongoDB deployment, include the following run-time
options with mongod
and mongos
:
sslOnNormalPorts
sslPEMKeyFile
with the.pem
file that contains the SSL certificate and key.
Consider the following syntax for mongod
:
For example, given an SSL certificate located at
/etc/ssl/mongodb.pem
, configure mongod
to use SSL
encryption for all connections with the following command:
Note
Specify
<pem>
with the full path name to the certificate.If the private key portion of the
<pem>
is encrypted, specify the encryption password with thesslPEMKeyPassword
option.You may also specify these options in the configuration file, as in the following example:
To connect, to mongod
and mongos
instances using
SSL, the mongo
shell and MongoDB tools must include the
--ssl
option. See SSL Configuration for Clients for more information on
connecting to mongod
and mongos
running with
SSL.
Set Up mongod
and mongos
with Certificate Validation¶
To set up mongod
or mongos
for SSL encryption
using an SSL certificate signed by a certificate authority, include the
following run-time options during startup:
sslOnNormalPorts
sslPEMKeyFile
with the name of the.pem
file that contains the signed SSL certificate and key.sslCAFile
with the name of the.pem
file that contains the root certificate chain from the Certificate Authority.
Consider the following syntax for mongod
:
For example, given a signed SSL certificate located at
/etc/ssl/mongodb.pem
and the certificate authority file at
/etc/ssl/ca.pem
, you can configure mongod
for SSL
encryption as follows:
Note
Specify the
<pem>
file and the<ca>
file with either the full path name or the relative path name.If the
<pem>
is encrypted, specify the encryption password with thesslPEMKeyPassword
option.You may also specify these options in the configuration file, as in the following example:
To connect, to mongod
and mongos
instances using
SSL, the mongo
tools must include the both the
--ssl
and
--sslPEMKeyFile
option.
See SSL Configuration for Clients for more information on connecting to
mongod
and mongos
running with SSL.
Block Revoked Certificates for Clients¶
To prevent clients with revoked certificates from connecting, include
the sslCRLFile
to specify a .pem
file that contains
revoked certificates.
For example, the following mongod
with SSL configuration
includes the sslCRLFile
setting:
Clients with revoked certificates in the /etc/ssl/ca-crl.pem
will not be able to connect to this mongod
instance.
Validate Only if a Client Presents a Certificate¶
In most cases it is important to ensure that clients present valid certificates. However, if you have clients that cannot present a client certificate, or are transitioning to using a certificate authority you may only want to validate certificates from clients that present a certificate.
If you want to bypass validation for clients that don’t present
certificates, include the sslWeakCertificateValidation
run-time option with mongod
and mongos
. If the
client does not present a certificate, no validation occurs. These
connections, though not validated, are still encrypted using SSL.
For example, consider the following mongod
with an SSL
configuration that includes the sslWeakCertificateValidation
setting:
Then, clients can connect either with the option --ssl
and no certificate or with the option --ssl
and a valid certificate. See SSL Configuration for Clients for more
information on SSL connections for clients.
Note
If the client presents a certificate, the certificate must be a valid certificate.
All connections, including those that have not presented certificates are encrypted using SSL.
SSL Configuration for Clients¶
Clients must have support for SSL to work with a mongod
or a
mongos
instance that has SSL support enabled. The current
versions of the Python, Java, Ruby, Node.js, .NET, and C++ drivers have
support for SSL, with full support coming in future releases of other
drivers.
mongo
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:
--ssl
--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.--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 Monitoring Agent¶
The Monitoring agent will also have to connect via SSL in order to gather its stats. 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.
Please 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:
Java¶
Consider the following example “SSLApp.java
” class file:
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
”.
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:
.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: