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:
- Roll your own with open source
step-ca
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.keyYour 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.pemfile. MongoDB requires the server certificate and key to be concatenated into one file. --tlsMode requireTLSensures encrypted connections with all clients.- When
mongodstarts 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
stepCLI 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.
To learn more, see Configuring step-ca Provisioners.
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 ca provisioner add mongodb --type JWK --create --x509-default-dur 720hFor instructions on adding provisioners to open source step-ca, or to learn more about other provisioner types, see Configuring step-ca Provisioners.
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.
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
--tlsAllowInvalidCertificatesis used here because we want to be able to rotate a potentially expired certificate. Usinglocalhosthere minimizes the security risk. - If the host system already trusts your CA, you can omit the
tlsCAFileparameter.
To start the renewal timer, run:
sudo systemctl daemon-reload
sudo systemctl enable --now cert-renewer@mongodb.timerYou'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.crtdirectly to theca-ceritficatesbundle on linux VMs so running applications trust the API servers they call - Bake
ca.crtdirectly into base Docker images for gRPC so gRPC clients can always reference the trusted CA - Store
ca.crtin a KubernetesSecretand inject it into an environment variable for access from application code - Use Jamf to install
ca.crtin the trust stores of every employee Macbook so their web browsers trust internal websites - Use Puppet to run
step certificate install ca.crton target machines that wantcurlto implicity trust the CA - Store
ca.crtin a KubernetesConfigMapand 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
- For MongoDB Atlas (the hosted MongoDB service), see Using a self-managed CA in MongoDB Atlas.
- For MongoDB Ops Manager (the control plane for MongoDB on-prem installations), see Enable TLS for a Deployment.
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.
Subscribe to updates
Unsubscribe anytime. See our privacy policy.
© 2023 Smallstep Labs, Inc. All rights reserved.