MongoDB TLS (Self-signed) — Guide for Ambience 202x

Ambience 2020+
1

Scope: Step-by-step, and annotated instructions to generate a self-signed CA, server and client certificates for MongoDB TLS, configure mongod, test with mongosh, and configure Ambience (including Java keystore/truststore details). Includes security notes and troubleshooting tips.

Important highlights

  • Modern TLS verification relies on Subject Alternative Names (SANs), not the certificate CN. Always include FQDN(s) and/or IP(s) in the SAN when creating CSRs; otherwise hostname verification will fail.

  • When testing with mongosh you can pass TLS files as CLI flags (–tlsCertificateKeyFile and --tlsCAFile). Do not rely on putting filesystem paths inside the MongoDB URI — most drivers do not accept file paths in the connection string. For applications, configure the driver or JVM TLS settings (keystore/truststore) instead.

  • Keep file names consistent. This document uses mongod-ca.* for the CA files and mongodb-HOST.* for server certs.

1) Generate CA key and self-signed CA certificate

# Generate private key (RSA 4096)
openssl genrsa -out mongod-ca.key 4096
# Generate self-signed CA certificate (10 years)
openssl req -x509 -new -nodes -key mongod-ca.key -sha256 -days 3650 -out mongod-ca.pem -subj “C=SG/ST=Singapore/L=Singapore/O=Elixir/OU=TechnicalServices/CN=MongoCA”

You can change subject fields; CN here is only descriptive—the CA must be trusted by clients.

2) Generate MongoDB server private key and CSR (repeat per server)

# Private key
openssl genrsa -out mongodb-HOST.key 4096
# CSR (include SANs directly when needed)
openssl req -new -key mongodb-HOST.key -out mongodb-HOST.csr -subj “/C=SG/ST=Singapore/L=Singapore/O=Elixir/OU=TechnicalServices/CN=hostname.elixir.com.sg”

Ensure SANs include the server FQDN/IP to avoid hostname verification failure.

3) Sign the server CSR with the CA (produce server certificate)

openssl x509 -req -in mongodb-HOST.csr -CA mongod-ca.pem -CAkey mongod-ca.key -CAcreateserial -out mongodb-HOST.crt -days 365 -sha256
# Combine key + cert into a PEM (MongoDB expects certificate+key in one file)
cat mongodb-HOST.key mongodb-HOST.crt > mongodb-HOST.pem
# Set tight permissions
chmod 600 mongodb-HOST.pem mongod-ca.pem
chown mongod:mongod mongodb-HOST.pem mongod-ca.pem   # adapt user/group

4) Generate MongoDB client certificate (for mutual TLS)

# Client private key
openssl genrsa -out mongo-client.key 4096
# Client CSR
openssl req -new -key mongo-client.key -out mongo-client.csr -subj “/CN=mongo-client”
# Sign client CSR with CA
openssl x509 -req -in mongo-client.csr -CA mongod-ca.pem -CAkey mongod-ca.key -CAcreateserial -out mongo-client.crt -days 365 -sha256
# Prepare PEM containing client key + certificate (for mongosh CLI)
cat mongo-client.key mongo-client.crt > mongo-client.pem
chmod 600 mongo-client.pem

5) MongoDB server configuration (mongod.conf)

net:
 tls:
   mode: requireTLS       # require TLS for all connections  
   certificateKeyFile: /etc/mongodb/ssl/mongodb-HOST.pem  
   CAFile: /etc/mongodb/ssl/mongod-ca.pem

Restart mongod after editing the config.

6) Test with mongosh

A) Connect using server cert file (server identity only)

mongosh --host hostname.elixir.com.sg:27017 --tls --tlsCAFile /etc/mongodb/ssl/mongod-ca.pem --tlsCertificateKeyFile /etc/mongodb/ssl/mongodb-HOST.pem

B) Connect with a client certificate (mutual TLS)

mongosh --host hostname.elixir.com.sg:27017 --tls –tlsCertificateKeyFile /etc/mongodb/ssl/mongo-client.pem –tlsCAFile /etc/mongodb/ssl/mongod-ca.pem

C) Replica set example

mongosh “mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=rs0&tls=true” –tlsCertificateKeyFile /etc/mongodb/ssl/mongo-client.pem --tlsCAFile /etc/mongodb/ssl/mongod-ca.pem

D) With authentication

mongosh --host host:27017 --tls --tlsCertificateKeyFile /etc/mongodb/ssl/mongo-client.pem –tlsCAFile /etc/mongodb/ssl/mongod-ca.pem --username admin --password ‘P@ssw0rd’

URL-encode special characters in passwords when used in connection strings.

7) Connection strings for Ambience (application.conf)

Standalone (TLS enabled):

mongodb://host:27017/?tls=true

Replica set (TLS enabled):

mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=rs0&tls=true

With credentials:

mongodb://username:password@host:27017/?tls=true

8) Java / Ambience: import client cert into PKCS#12 and JKS, import CA into truststore

# Create PKCS#12
openssl pkcs12 -export -in mongo-client.crt -inkey mongo-client.key -out mongo-client.p12 -name mongoClient -certfile mongod-ca.pem
# Import PKCS#12 into JKS
keytool -importkeystore -deststorepass changeit -destkeystore mongo-client.jks -srckeystore mongo-client.p12 -srcstoretype PKCS12 -alias mongoClient
# Import the CA into a Java truststore
keytool -importcert -trustcacerts -alias mongo-CA -file mongod-ca.pem -keystore /opt/mongo-truststore.jks -storepass changeit

9) Configure JVM properties when starting Ambience

-Djavax.net.ssl.trustStore=/opt/mongo-truststore.jks
-Djavax.net.ssl.trustStorePassword=changeit
-Djavax.net.ssl.keyStore=/path/to/mongo-client.jks
-Djavax.net.ssl.keyStorePassword=changeit

For Services:

<startarguement>-Djavax.net.ssl.trustStore=/opt/mongo-truststore.jks</startarguement>
<startarguement>-Djavax.net.ssl.trustStorePassword=changeit</startarguement>
<startarguement>-Djavax.net.ssl.keyStore=/path/to/mongo-client.jks</startarguement>
<startarguement>-Djavax.net.ssl.keyStorePassword=changeit</startarguement>

Optional troubleshooting: -Djdk.tls.client.protocols=TLSv1.2

10) Troubleshooting checklist

  • Confirm server cert contains FQDN/IP in SAN.

  • Ensure mongod has certificate+key in PEM and CAFile is readable.

  • Verify permissions (600) and ownership.

  • Check JVM keytool version matches Ambience JDK.

  • URL-encode passwords in connection strings.

11) Security & operational notes

  • Self-signed CAs suitable for internal/testing; use enterprise CA for production.

  • Protect mongod-ca.key; compromise requires reissuing all certs.

  • Monitor certificate expiry and rotate periodically.