Upcoming change to TLS certificates: Addition of Google Trust Services with Let's Encrypt

Background

MongoDB Atlas requires Transport Layer Security (TLS) encryption for customer data and intra-cluster network communications. MongoDB Atlas uses Let’s Encrypt as the Certificate Authority (CA) for TLS certificates for all clusters.

To improve availability, we are adding Google Trust Services as an additional CA for Atlas clusters. Prior to June 2025, you must ensure that your application recognizes certificates from both Let’s Encrypt and Google Trust Services:

Add GTS Root R1 and GTS Root R2 (from Google Trust Services) into your application’s trust store. Doing this ensures your application recognizes certificates from both CAs.
As a best practice, avoid hardcoding or pinning specific intermediate CAs in your application. Instead, ensure your application’s trust store accepts all recognized root CAs to maintain flexibility, following best practices from MongoDB and Google Trust Services.

Note: You cannot control the timing of the TLS CA change; however, it will respect your configured project maintenance window.

For your reference, the root CA certificates for the Google Trust Store can be found at https://pki.goog/repository/ under the "Root CAs" section.

How to check if the certificates are present in your environment

You can verify whether these certificates are already included in your environment by following these steps:

Use the following curl command to trace the connection and log the details:
```
curl --trace - https://<Atlas host name>:27017 > curl.log
```
Search for the path of the CA file in the curl.log by running:
```
cat curl.log | grep "pem"
```
Once you have the path to your CA file, use the following command to check for specific root certificates:
```
cat <CA File> | grep -E "GTS Root R1|GTS Root R2|ISRG Root X1"
```
Replace <CA File> with the actual path to your CA file.
In the output, you should look for entries similar to:
GTS Root R1, O=Google Trust Services LLC, C=US
GTS Root R2, O=Google Trust Services LLC, C=US

You can also use the following command which will establishes a secure TLS connection to the MongoDB Atlas cluster and retrieve the SSL/TLS certificates presented by the server. It helps in verifying the certificate chain.

openssl s_client -connect <node_hostname>:27017 -showcerts

Note: Replace <node_hostname> with the hostname of any primary or secondary node in your cluster. You can find these details in the "View Monitoring" or METRICS tab in the Atlas UI (for example, clustername-shard-00-01.xxxxx.mongodb.net).

For Linux environment

The location of the default root certificates store varies depending on operating system and SSL/TLS library used. However, on most Linux distributions, the default root certificates can be found under one of the following paths:

/usr/local/share/ca-certificates: Debian, Ubuntu, older RHEL, and CentOS versions
/etc/pki/ca-trust/source/anchors and /usr/share/pki/ca-trust-source: Fedora, newer RHEL, and CentOS versions
/var/lib/ca-certificates: OpenSUSE

Other certificate paths may include:

/etc/ssl/certs: Debian, Ubuntu
/etc/pki/tls/certs: RHEL, CentOS

Some certificates in these directories are likely symbolic links to files in other directories. You can use the steps mentioned above to check for the presence of GTS Root Certificates on your Linux machines.

For Windows-based virtual machines

To verify certificates in the Local Machine Trusted Root Certification Authorities store on a Windows system, you can use the following PowerShell command:

Get-ChildItem -Path Cert:\LocalMachine\Root

You can also check the Trusted Root Certification Authorities Certificate Store through the Windows GUI. For detailed instructions, see the Azure documentation on Trusted Root Certification Authorities Certificate Store.

Note: For App Services and Cloud Functions that are Azure cloud offerings, we recommend reaching out to Azure support. They can provide assistance in verifying CA certificate details from the backend environment.

For AWS environment

If your application is hosted on AWS (EC2 machine), you can check if the required CAs are already available in your environment by running the following command from the environment's CLI:

openssl x509 -in /etc/ssl/certs/ca-bundle.crt -text -noout | grep -A2 "GTS Root R"

Alternatively, if you're using AWS Certificate Manager, see the official AWS documentation to list the certificates.

Note: If your application server is running inside a container (AWS ECS/EKS) or using AWS Lamda, you must contact AWS support to verify whether the container/pod's trust store contains the GTS Root R1 and GTS Root R2 certificates.

For Java-based applications

Java applications might use their own root certificates store We suggest checking if GTS Root R1 and GTS Root R2 certificates are already listed in your Java trust store using the keytool (for Solaris, Linux, or macOS; or Windows). For additional details, see the Java-Security documentation.

Note: The following sections are based on the documentation for Oracle JDK, so some parts may be inapplicable to your JDK or to the custom TLS/SSL implementation you use.

To list the certificates in the trust store:

keytool -list -keystore $JAVA_HOME/lib/security/cacerts -storepass <password>

To ensure if GTS Root R1, GTS Root R2, and ISRG Root X1 are present by filtering the output:

keytool -list -keystore $JAVA_HOME/lib/security/cacerts -storepass <password> | grep -E "gts-root|isrg-root"

If these are not part of your trust store, you may -importcerts using the keytool. For example:
```
keytool -importcert -file <certificate_file> --alias <any-alias_name>
```

See the Enable TLS/SSL on a Connection in Java documentation for more details. For Kotlin based applications, see the Enable TLS/SSL on a Connection documentation.

For Python-based applications

Locate the certificate bundle:
- Python uses the certifi library for its CA bundle. You can find the location of this bundle with:
```
python -m pip show certifi python -c "import certifi; print(certifi.where())"
```
  See the PyPi certifi documentation for additional details.
Check for required certificates:
- Open the CA bundle file (located in the path printed by certifi.where()) and search for GTS Root R1, GTS Root R2, and ISRG Root X1:
```
cat <path_to_certifi_bundle> | grep -E "GTS Root R1|GTS Root R2|ISRG Root X1"
```

See the Configure Transport Layer Security (TLS) with Python documentation for more details.

Retrieving root certificates in Node.js

Node.js maintains a list of trusted root certificates accessible through the tls.rootCertificates property. This property returns an array of PEM-encoded certificates. You can iterate through this array to check for specific certificates, such as GTS Root R1 and GTS Root R2.

Example script:

const tls = require('tls'); // Retrieve the list of root certificates const rootCerts = tls.rootCertificates; // Check for GTS Root R1 and GTS Root R2 const gtsRootR1 = rootCerts.find(cert => cert.includes('GTS Root R1')); const gtsRootR2 = rootCerts.find(cert => cert.includes('GTS Root R2')); console.log(`GTS Root R1 Trusted: ${gtsRootR1 ? 'Yes' : 'No'}`); console.log(`GTS Root R2 Trusted: ${gtsRootR2 ? 'Yes' : 'No'}`);

See the Node.js tls.rootCertificates Property documentation for more details.

The MongoDB drivers usually rely on the operating system's trust store (such as Windows or Linux) to validate TLS certificates, unless a custom trust store is configured for your application. If the required certificates are already included in your environment's trust store, no additional action is necessary.

Some network devices, such as firewalls or proxies, might intercept SSL connections for monitoring or filtering and present their own certificates instead of the ones from MongoDB Atlas. If these CAs are not in the trust store, you may experience an SSLHandshakeException error.

FAQs

Do the above changes apply to all cluster nodes?

The above changes apply to all Atlas dedicated tier clusters.

What changes is Atlas making with respect to the X.509 Certificate Authority?

MongoDB is onboarding Google Trust Service (GTS) as an alternative CA for Atlas. It will be actively used with Let's Encrypt Certificate Authority at no additional cost.

What is the expected timeline?

We will start making the changes from June 2025 onwards.

Are the new CA certificates cross-signed by both Let's Encrypt and Google Trust Service?

In a cluster, TLS certificates will be signed by Let’s Encrypt for some nodes and by Google Trust Services for others. Certificates will not be cross-signed.