MongoDB TLS (Signed) — Guide for Ambience 202x

Ambience 2020+
1

Scope: Step-by-step, and annotated instructions for 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) Require Root and Intermediate Certificates(Given by Customer)

#Combine root and intermediate Certificate
cat root.cer intermediate.cer > chain_cert.pem

Ensure that the customer gives you both a root certificate and intermediate certificate. This 2 certificate is the one that signed both the server and client certificate.

Handshake will fail if the certificate does not match with the root and intermediate certificate.

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”
# After generating the server certificate, give the customer CSR certificate that was generated. Ensure that the given signed certificate is formatted correctly(base64).

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

3) Combine the Signed server certificate given

# Combine key + cert into a PEM (MongoDB expects certificate+key in one file)
cat mongodb-HOST.key mongodb-HOST.cer > 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”
# After generating the server certificate, give the customer CSR certificate that was generated. Ensure that the given signed certificate is formatted correctly(base64).
# Prepare PEM containing client key + certificate (for mongosh CLI)
cat mongo-client.key mongo-client.cer > 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/chain_cert.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/chain_cert.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/chain_cert.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/chain_cert.pem

D) With authentication

mongosh --host host:27017 --tls --tlsCertificateKeyFile /etc/mongodb/ssl/mongo-client.pem --tlsCAFile /etc/mongodb/ssl/chain_cert.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 Root into a Java truststore
keytool -importcert -trustcacerts -alias Root-CA -file root.cer -keystore /opt/mongo-truststore.jks -storepass changeit
# Import the intermediate into a Java truststore
keytool -importcert -trustcacerts -alias Intermediate-CA -file intermediate.cer -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 the Ambience JDK.

  • URL-encode passwords in connection strings.