SSL for MongoDB Connections
- Configuring SSL
- Connecting over SSL
- Choosing an SSL domain scope
- Frequently asked questions (FAQ)
- Q. How do you manage SSL certificates?
- Q. Why choose mLab’s SSL offfering?
- Q. What SSL modes do you support?
- Q. Do you support authenticating clients with an X.509 certificate?
- Q. Should I be worried about the “no SSL certificate provided by peer” errors in my logs?
- Q. Do you support one key pair per deployment?
- Q. Do you have any driver configuration examples?
mLab offers SSL support for MongoDB connections as an option on all Dedicated plans provisioned via mlab.com. Enabling SSL adds another level of security for communication between the application and database, allowing clients to open encrypted connections to the database servers and then verify the identity of those servers before sending any sensitive information.
Even when using SSL to secure your connections to MongoDB, we still recommend placing your application infrastructure and your database in the same datacenter / cloud region, to minimize network latency and take advantage of the network security features offered by the cloud provider.
Available for Dedicated plans only
Whether creating a new deployment or upgrading an existing deployment, you can enable SSL support for MongoDB connections directly from the mLab management portal.
Enabling SSL when creating a new deployment
Upgrading an existing deployment to enable SSL
If you have an existing deployment, you can enable SSL from the Tools tab for that deployment. The option will only appear if the deployment is subscribed to a Dedicated plan that was provisioned via mlab.com.
When you’re ready to enable SSL, follow these steps:
- Log in to the mLab management portal.
- From your account’s Home page, navigate to the deployment that will be modified.
- Click the “Tools” tab.
- Under the “Initiate maintenance operation” header, select the “Enable SSL” option.
- Select the desired domain scope in the drop-down menu that appears under “This deployment currently does not have SSL enabled…””
- Click the “Enable…SSL” button and confirm that you want to proceed. This will initiate the process of enabling SSL on your deployment.
- Wait for the process to complete.
- Update your driver configuration to connect over SSL, keeping in mind that the DNS names in your connection string have likely been changed to use your chosen SSL domain scope.
The upgrade process will require a replica set reconfiguration to move the deployment into the target SSL domain followed by two rolling restarts of the entire deployment to step through the MongoDB SSL modes from disabled to allowSSL and finally preferSSL. While a well-configured client will handle this operation gracefully, we recommend scheduling the upgrade for a time when you can monitor your application in case of any unexpected issues.
Enabling SSL is likely to change the DNS names of the servers in your deployment which, in turn, will cause your connection string to change. We will leave the old DNS names bound for a period of time to give you time to transition. However, the certificates used to establish SSL connections will use the new DNS names, so clients attempting to connect using SSL will need to use the new connection string.
After enabling SSL, the old connection string will work only until we have to perform certain maintenance operations (e.g., a plan change) that require a rolling node replacement. Therefore, ALL clients attempting to connect - whether or not they are connecting using SSL - will need to use the new connection string.
Disabling SSL for a deployment
When you need to disable SSL, follow these steps:
- Log in to the mLab management portal.
- From your account’s Home page, navigate to the deployment that will be modified.
- Click the “Tools” tab.
- Under the “Initiate maintenance operation” header, select the “Disable SSL” option.
- Click the “Disable SSL” button and confirm that you want to proceed.
- Wait for the rolling restart process to complete (see explanation below).
- Update your application to use the new connection string that has the SSL domain scope removed.
Disabling SSL will prompt a rolling restart of each process in this deployment to change MongoDB SSL modes (from preferSSL to disabled). Restarting your primary will require failover and the original primary node will be reinstated as primary upon completion.
Disabling SSL will cause the DNS names in your connection string to change such that the SSL domain scope will be removed. You must then use the new connection string, as the previous connection string will not function beyond the next maintenance event.
Fees (now free)
As of October 1, 2017, mLab no longer charges for SSL, even on existing deployments with SSL enabled.
Prior to this date, SSL domains incurred an additional monthly charge of $80, pro-rated on a daily basis. Account-scoped SSL domains (now deprecated) would incur a single monthly charge regardless of the number of deployments using that SSL domain. Each deployment-scoped SSL domain in your account incurred a separate charge.
Connecting over SSL
To be sure you are taking full advantage of SSL for MongoDB connections, it is important to correctly configure your driver and verify that it is connecting securely. In particular, you want to be confident that SSL is being used and that the server is being authenticated using the certificate it presents.
Configuring your driver to use SSL securely
The latest version of most drivers will create secure SSL connections using browser-like server authentication if you specify
ssl=true as an option in the connection string URI. However, some drivers require additional options to connect securely. For example, some older driver versions need to have host name validation enabled or need to be provided an explicit list of trusted certificates.
MongoDB, Inc. provides some driver-specific documentation about connecting using SSL. Of course, you should consult your driver’s documentation for more information.
Eventually, we will be publishing in the Language Center examples of how to securely connect to your SSL-enabled mLab deployment using each of the drivers our customers use most often. Keep an eye out there for an example in your driver of choice.
Verifying the security of your SSL connection
While it can be complicated and time consuming to test all the security features of SSL, there is a simple test we recommend to cover the most common cases of misconfiguration. Simply try connecting with two different connection strings (with placeholders filled in, of course):
- Your normal connection string as shown in the mLab management portal
- The same connection with each host name replaced by its current IP address
If connecting with host names succeeds but connecting with IPs fails with an SSL validation error, you can be confident that your driver is connecting over SSL, requesting a certificate from the server, and checking the host name against the certificate presented.
A successful result does not mean that every possible authentication test is being performed, but in our experience host name verification is the test most often skipped, so it is a good litmus test to use.
Use of IPs in connection strings is not supported in permanent configurations. The host names your deployment uses will rarely change except to add or remove features such as additional servers or changing of SSL domain scopes.
Hardening your SSL configuration (optional)
As an optional step, consider the following steps to harden your SSL configuration:
Upgrade your driver to the latest stable version. The most recent driver versions will contain security patches. If upgrading to the latest stable driver version is too onerous, at the very least you should upgrade to the most recent patch release on the code line you’re already using.
Configure your clients to trust only those certificates you know you need to use. All SSL-enabled MongoDB deployments hosted by mLab will use certificates signed by the same root certificate. See below for instructions on how to download and use that certificate.
Downloading and using mLab’s root certificate
All certificates used to protect SSL-enabled MongoDB deployments hosted by mLab will be signed by the “DigiCert Global Root CA” which can be downloaded from DigiCert’s list of root certificates.
Be aware that the certificates will download in the DER binary format, whereas most drivers expect a PEM ASCII-based format certificate. There are many tools available, such as
openssl, to convert between the two formats.
Most drivers validate SSL certificates against the canonical set of trusted certificates distributed either with your language or your operating system. Consult your driver or client docs for how to trust only an explicit list of certificates, sometimes called CA certificates.
Choosing an SSL domain scope
Each SSL-enabled deployment belongs to exactly one SSL domain, consisting of:
- a DNS domain
- the certificates and key pairs used to secure all SSL connections made to or from servers in that domain
The scope of an SSL domain defines:
- the power of the certificates and key pairs used to secure SSL connections
- the breadth of their distribution
Narrowly-scoped SSL domains are more secure than broadly-scoped domains as they limit the applicability of the SSL certificates and key pairs used and limit the places to which those assets need to be deployed.
To make the choice of SSL domain scope more convenient, we define two pre-packaged scopes, described in more detail in the sections below:
- Account scope
- Deployment (cluster) scope
You can mix and match scopes within the same mLab account. For example, if you have five development clusters and two production clusters all in the same account, you could put the development clusters within an account scope SSL domain and put each production cluster in their own deployment scope SSL domain, for a total of three domains.
Each domain you use will incur a monthly charge.
To read more about how we manage SSL certificates, see the section below, How mLab manages SSL certificates.
All servers in this scope will be in a subdomain of fleet.mlab.com unique to your account. The exact subdomain will be randomly generated. This domain will be shared with all clusters in the mLab account that also choose the account scope.
This scope balances security with cost. The certificate used is shared among the other deployments in the same account using this scope, keeping costs down, but is not shared with any other mLab accounts, isolating the account from security breaches in other accounts.
All servers in this scope will be in a subdomain of fleet.mlab.com unique to your deployment (cluster). The exact subdomain will be randomly generated. This domain will not be shared with any other deployments in your mLab account.
This scope maximizes security at increased cost since each deployment will use its own unique certificate, isolating the deployment from security breaches in other deployments, including those within the same account.
It is possible to change the scope of an SSL domain, but the work involved to do this will require downtime and a change in your connection string. Contact us at firstname.lastname@example.org to discuss moving your deployment to a different SSL domain scope.
Frequently asked questions (FAQ)
Q. How do you manage SSL certificates?
mLab manages all certificates required to support SSL connections to your MongoDB deployment. There is no need to generate or manage certificates yourself.
mLab’s certificate authority is DigiCert, one of the most respected issuers in the industry, with widely-distributed root certificates. As such, you should not need to install a special root certificate on your application servers in order to validate the SSL certificates presented by SSL-enabled mLab deployments, though you may consider doing so to harden your configuration.
New certificates are provisioned by mLab as needed during the deployment provisioning process and as necessary during any upgrades or maintenances. We have worked with our issuer to automate this process so that it is both reliable and fast.
When generating certificates, the key pair never leaves the virtual machine (VM) on which it will be used and is encrypted using a cryptographically-random password that is encrypted and stored in a location not accessible from the VM.
Q. Why choose mLab’s SSL offfering?
We use a premium certificate authority (DigiCert) to make it as simple as possible to correctly and securely configure SSL. Because DigiCert’s root certificates are well trusted and distributed, most drivers will authenticate them without further configuration.
Your certificate will never be shared with other accounts and customers. While it was something we considered offering, we feel sharing certificates across accounts is a mistake because it has the potential of exposing one customer to the mistakes of another.
Q. What SSL modes do you support?
Currently, all deployments with SSL enabled use the preferSSL net.ssl.mode which guarantees that SSL is used for all communication between the nodes of a deployment, but allows other clients to connect with or without SSL.
In the future, we may support requireSSL which requires SSL for all connections and rejects all connections that don’t use SSL.
Q. Do you support authenticating clients with an X.509 certificate?
No, mLab’s deployments do not support client authentication with X.509 certificates at this time.
Q. Should I be worried about the “no SSL certificate provided by peer” errors in my logs?
There is no need to worry; this message is completely normal when connecting to any of mLab’s SSL-enabled deployments. It is simply warning that the client didn’t provide X.509 client certificates for authentication, but that is to be expected since mLab currently does not support client authentication with X.509 certificates.
2016-01-01T00:00:00.400-0700 I NETWORK [initandlisten] connection accepted from 100.200.300.400:50000 #9999 (10 connections now open) 2016-01-01T00:00:00.500-0700 W NETWORK [conn9999] no SSL certificate provided by peer 2016-01-01T00:00:00.600-0700 I ACCESS [conn9999] Successfully authenticated as principal testdbuser on testdatabase
A few key points to note from the log snippet (MongoDB 3.2) above:
- The offending message is simply a warning message, as indicated by “W” on the second line.
- Even though X.509 client certificates were not provided to authenticate, client authentication did happen later on (we happen to know this was done with a username/password challenge).
- MongoDB treats the SSL handshake and authenticating as potentially independent phases of the connection lifecycle.
Q. Do you support one key pair per deployment?
Not at this time. Eventually, we will create a unique key pair per VM to which a certificate is deployed. This increases the power of each key pair should it be stolen as well as the surface area an attacker can use to try to steal it. Until then, however, all servers in all deployments sharing a single SSL domain will use the same key pair.
Q. Do you have any driver configuration examples?
To take the guesswork out of configuring your driver, over time we will be publishing examples for how to securely connect over SSL to mLab-hosted deployments using the drivers we see our customers using the most. The examples will be listed in our Language Center.
Have feedback? We welcome feedback at any time. SSL certificate management, SSL-related features, and security in general are nuanced but important subjects so contact us at email@example.com with your input.