MongoDB TLS — Practical Zero Trust

How to get and renew MongoDB TLS certificates

Written October 27, 2021

Zero Trust or BeyondProd approaches require authenticated and encrypted communications everywhere. TLS is the cryptographic protocol that powers encryption for all your technologies. For TLS, you need certificates. This practitioner's tutorial provides instructions for automating MongoDB TLS certificate renewal and enabling server-side encryption.

Try it

Create a private key and request a certificate

Before you can configure MongoDB TLS, you will need a certificate issued by a trusted certificate authority (CA). If you already have a certificate, private key, and CA root certificate from your organization's existing CA, you can skip to the MongoDB TLS configuration section below. If you need to generate a certificate, you can:

To request a certificate from your CA using the step CLI, bootstrap your CA with step ca bootstrap and run the following command (sub the server name for the actual name / DNS name of your MongoDB server).

step ca certificate "mongodb.example.net" server.crt server.key

Your certificate and private key will be saved in server.crt and server.key respectively.

Request a copy of your CA root certificate, which will be used to make sure each application can trust certificates presented by other applications.

step ca root ca.crt

Your certificate will be saved in ca.crt.

Configure MongoDB to use the certificate

You can test your certificate by starting up MongoDB with TLS enabled.

Start up a MongoDB server using server authenticaiton:

cat server.crt server.key > merged.pem mongod --tlsMode requireTLS \ --tlsCAFile ca.crt \ --tlsCertificateKeyFile merged.pem
  • Notice the merged.pem file. MongoDB requires the server certificate and key to be concatenated into one file.
  • --tlsMode requireTLS ensures encrypted connections with all clients.
  • When mongod starts up, you should see "ssl":"on" in its log output.

Test MongoDB TLS configuration

Next, in another terminal, use the mongosh client to connect to your server:

$ mongosh "mongodb://mongodb.example.net:27017?tls=true&tlsCAFile=ca.crt"

Operationalize It

On our blog, we've written an in-depth series of posts and examples for using MongoDB with TLS. While these are geared toward our open source CA, the same configurations can be used with Certificate Manager too.

Select a provisioner

Smallstep CAs use provisioners to authenticate certificate requests using passwords, one-time tokens, single sign-on, and a variety of other mechanisms.

  • ACME (RFC8555) is an open standard, used by Let's Encrypt, for authenticating certificate requests. To use ACME on a private network you need to run an ACME server. ACME is harder to setup, but has a large client ecosystem (some software even has built-in support).
  • Other provisioners use the open source step CLI and do not require a local network agent. The instructions below focus on the JWK provisioner, but can be repurposed with small tweaks to operationalize all non-ACME provisioners.
Show me instructions for...

The right provisioner depends on your operational environment.

The JWK provisioner is the most general-purpose provisioner. It supports password and one-time token-based authentication. To add a JWK provisioner called mongodb to a hosted Certificate Manager authority (if you haven't already), run:

step beta ca provisioner add mongodb --type JWK --create --x509-default-dur 720h

For instructions on adding provisioners to open source step-ca, or to learn more about other provisioner types, see Configuring step-ca Provisioners.

The ACME protocol requires access to your internal network or DNS in order to satisfy ACME challenges. For hosted Certificate Manager CAs, you'll need to configure an ACME Registration Authority on your network that will act as an ACME agent to Certificate Manager.

Configure MongoDB TLS Certificate Automation

We've created a systemd-based certificate renewal timer that works with step. Check out our documentation on Renewal using systemd timers for background on how these timers work.

To install the certificate renewal unit files, run:

cd /etc/systemd/system sudo curl -sL https://files.smallstep.com/cert-renewer@.service \ -o cert-renewer@.service sudo curl -sL https://files.smallstep.com/cert-renewer@.timer \ -o cert-renewer@.timer

The renewal timer will check your certificate files every five minutes and renew them after two-thirds of their lifetime has elapsed.

We've created a systemd renewal timer for renewing certificates with a Smallstep CA (see non-ACME Linux instructions). However, we haven't yet investigated how to modify that timer for ACME use cases. We're working on it, but feel free to contribute this content directly on GitHub. At this point, you will need to manually create the cert-renewer@.service and cert-renewer@.timer template files.

To renew and hot-reload the MongoDB server certificate, we will need a MongoDB-specific systemd override file that can tell MongoDB to refresh its certificates. To install the override, run:

sudo mkdir /etc/systemd/system/cert-renewer@mongod.service.d cat <<EOF | sudo tee /etc/systemd/system/cert-renewer@mongod.service.d/override.conf [Service] ; Empty ExecStartPost (Don't attempt to restart mongod.service) ExecStartPost= ExecStartPost=bash -c 'cat \$CERT_LOCATION \$KEY_LOCATION > /etc/step/certs/mongo.pem' ExecStartPost=bash -c 'mongosh --tlsAllowInvalidCertificates "mongodb://localhost:27017?tls=true&tlsCAFile=/etc/step-ca/certs/root_ca.crt" -f <(echo "db.adminCommand( { rotateCertificates: 1 } )")' EOF
  • Note that --tlsAllowInvalidCertificates is used here because we want to be able to rotate a potentially expired certificate. Using localhost here minimizes the security risk.
  • If the host system already trusts your CA, you can omit the tlsCAFile parameter.

To start the renewal timer, run:

sudo systemctl daemon-reload sudo systemctl enable --now cert-renewer@mongodb.timer

You'll see that the timer is active, by checking the output of systemctl list-timers.

Distribute your root certificate to end users and systems

Once MongoDB TLS is configured, you'll need to make sure that clients know to trust certificates signed by your CA. For certificates signed by a public CA (like Let's Encrypt), most clients already include the CA root certificate in their trust stores for certificate verification. But, for a private CA, you will need to explicitly add your CA's root certificate to your clients' trust stores.

The step CLI includes a utility command for this purpose on many systems:

step certificate install ca.crt

Rather than manually running the above for each machine that needs to trust your CA, most teams will use some form of automation to distribute the root certificate. Depending on your needs and your IT or DevOps team's approach, this may be a configuration management tool (like Ansible or Puppet), a Mobile Device Management (MDM) solution, or something else. Some examples:

  • Use Ansible to add ca.crt directly to the ca-ceritficates bundle on linux VMs so running applications trust the API servers they call
  • Bake ca.crt directly into base Docker images for gRPC so gRPC clients can always reference the trusted CA
  • Store ca.crt in a Kubernetes Secret and inject it into an environment variable for access from application code
  • Use Jamf to install ca.crt in the trust stores of every employee Macbook so their web browsers trust internal websites
  • Use Puppet to run step certificate install ca.crt on target machines that want curl to implicity trust the CA
  • Store ca.crt in a Kubernetes ConfigMap and mount it to pods for reference on the filesystem

Alternatively, many clients support passing the CA root certificate as a flag or argument at runtime.

Further reading

Contribute to this document

The Practical Zero Trust project is a collection of living documents detailing TLS configuration across a broad spread of technologies. We'd love to make this document better. Feel free to contribute any improvements directly on GitHub.