OneDB supports secure connections for MongoDB database traffic through the OneDB Listener. This allows MongoDB client applications to connect to OneDB using an encrypted SSL/TLS connection before the traffic is forwarded to the target MongoDB Database.

Secure Connection is useful when applications are required to protect database communication over the network, especially in environments where security policies require encrypted database connections.

Before You Begin

Before configuring the MongoDB client, make sure the following items are already prepared:

1. The MongoDB Database connection has been registered in OneDB.
2. The OneDB Listener has been created for the MongoDB connection.
3. Secure Connection has been enabled on the OneDB Listener.
4. The listener port is open and reachable from the client machine.
5. The OneDB SSL/TLS certificate has been generated or imported.
6. The required CA certificate is available on the MongoDB client side.
7. The hostname or IP address used by the MongoDB client is included in the OneDB certificate Subject Alternative Name (SAN).

Listener Configuration in OneDB

In OneDB Web Console, go to the Listener configuration page and create or edit a MongoDB listener.

Make sure the following settings are configured:

After saving the listener configuration, start or reload the listener.

MongoDB Client Connection Format

For secure MongoDB connections, use the standard MongoDB connection string with the tls=true option.

Example connection string:

mongodb://<username>:<password>@onedb-listener-host:27017/?authSource=admin&tls=true

Replace the following values based on your environment:

MongoDB clients validate the certificate presented by the OneDB Listener. The hostname or IP address in the connection string must match a DNS name or IP address included in the certificate SAN. MongoDB clients use TLS validation when tls=true is enabled.

Example Using MongoDB Compass

MongoDB Compass can connect to the OneDB Listener using SSL/TLS.

1. Open MongoDB Compass.
2. Enter the OneDB Listener hostname or IP address.
3. Enter the secure listener port configured in OneDB.
4. Configure the required MongoDB authentication settings.
5. Open the TLS/SSL configuration section.
6. Enable SSL/TLS.
7. Select the CA certificate that is used to validate the OneDB Listener certificate.
8. Connect to the OneDB Listener.

Example connection string:

mongodb://<username>:<password>@onedb-listener-host:27017/?authSource=admin&tls=true

For production environments, keep certificate and hostname validation enabled.

Example Using mongosh

MongoDB Shell (mongosh) can connect securely to the OneDB Listener using the --tls option.

Example:

mongosh "mongodb://<username>:<password>@onedb-listener-host:27017/?authSource=admin" \
  --tls \
  --tlsCAFile /path/to/onedb-ca.pem

Replace the hostname, listener port, authentication source, and CA certificate path based on your environment.

The --tlsCAFile option provides the CA certificate used by mongosh to validate the certificate presented by the OneDB Listener. MongoDB validates both the issuing CA and the hostname against the certificate SAN.

Example Using MongoDB Drivers

MongoDB drivers can enable SSL/TLS through the connection string or driver-specific settings.

Example connection string:

mongodb://<username>:<password>@onedb-listener-host:27017/?authSource=admin&tls=true

Example using the MongoDB Node.js driver:

const { MongoClient } = require("mongodb");

const uri =
  "mongodb://<username>:<password>@onedb-listener-host:27017/?authSource=admin&tls=true";

const client = new MongoClient(uri, {
  tls: true,
  tlsCAFile: "/path/to/onedb-ca.pem"
});

MongoDB drivers support enabling TLS by setting tls=true in the connection string or client configuration.

Certificate Validation

The OneDB certificate must contain the hostname or IP address used by MongoDB clients.

For example, when MongoDB clients connect to:

mongodb://mongodb-listener.example.com:27017/?tls=true

the OneDB certificate should include:

DNS:mongodb-listener.example.com

When clients connect using an IP address, the certificate should include the corresponding IP SAN entry.

IP:192.168.1.10

MongoDB clients verify the hostname against the certificate SAN. When a SAN is present, the client validates the SAN rather than the certificate Common Name.

Testing the Connection

After the listener and MongoDB client configuration are ready, test the connection using mongosh, MongoDB Compass, or the application connection pool.

Example:

mongosh "mongodb://<username>:<password>@onedb-listener-host:27017/?authSource=admin" \
  --tls \
  --tlsCAFile /path/to/onedb-ca.pem

After a successful connection, run a simple command:

db.runCommand({ ping: 1 })

If the command succeeds, the MongoDB client is connected through the OneDB Listener using a secure SSL/TLS connection.

Troubleshooting

Unable to connect to the listener

Check that the OneDB Listener is running and the listener port is open from the client machine.

nc -vz onedb-listener-host 27017

TLS handshake failed

Check that the MongoDB client trusts the CA certificate used by the OneDB Listener.

For mongosh, confirm that the CA certificate path is correct:

--tlsCAFile /path/to/onedb-ca.pem

Hostname validation failed

Make sure the hostname or IP address used in the MongoDB connection string is included in the OneDB certificate SAN.

For example, if the client connects using:

mongodb://mongodb-listener.example.com:27017/?tls=true

The certificate must contain:

DNS:mongodb-listener.example.com

Certificate is not trusted

Import or configure the correct CA certificate on the MongoDB client.

Avoid using tlsAllowInvalidHostnames=true, tlsAllowInvalidCertificates=true, or other insecure TLS options in production. These options may encrypt the connection but bypass certificate validation.

Application still using a non-secure connection

Make sure the MongoDB connection string includes:

tls=true

Example:

mongodb://<username>:<password>@onedb-listener-host:27017/?authSource=admin&tls=true

Summary

MongoDB applications can connect securely to the OneDB Listener using SSL/TLS. By enabling Secure Connection on the listener and configuring MongoDB clients to use tls=true, database traffic from the application to OneDB can be protected over the network.

This setup is recommended for environments that require encrypted database connectivity and stronger protection between applications and database access points.