Enabling TLS with a Self‐Signed Certificate in ORDS for MongoDB API

Overview

This runbook describes how use the self-signed certificate Oracle REST Data Services (ORDS) generates for usage with the Oracle Database API for MongoDB. It enables TLS communication for development or internal use cases.

1. Prerequisites

  • ORDS version 22.3 or later
  • Installation based on Quick Start Guide
  • ORDS is installed and configured in standalone mode
  • MongoDB API is enabled in ORDS
  • ORDS configuration directory is located at /home/oracle/ords_config
  • OpenSSL installed on the system

2. Create Self-Signed Certificate for ORDS and MongoDB utilities

ORDS will by default create self-signed certificates but MongoDB utilities require additional things. In order to test TLS connections to the Oracle Database API for MongoDB using MongoDB utilities we will create the required certificate.

To explicitly control how OpenSSL creates the certificate files we make a specific configuration like so:

cat > /tmp/ords_cert.cnf <<EOF
[req]
default_bits = 2048
prompt = no
default_md = sha256
req_extensions = req_ext
distinguished_name = dn

[dn]
CN = localhost

[req_ext]
basicConstraints = critical,CA:TRUE
keyUsage = digitalSignature, keyCertSign, cRLSign
subjectAltName = @alt_names

[alt_names]
DNS.1 = localhost
EOF

To support certificates files using an IP address, localhost, and alias names use the following configuration:

cat > /tmp/ords_cert.cnf <<EOF
[req]
default_bits = 2048
prompt = no
default_md = sha256
req_extensions = req_ext
distinguished_name = dn

[dn]
CN = localhost
#CN = 10.0.0.80

[req_ext]
basicConstraints = critical,CA:TRUE
keyUsage = digitalSignature, keyCertSign, cRLSign
subjectAltName = @alt_names

[alt_names]
IP.1 = 10.0.0.78
DNS.1 = localhost
DNS.2 = orcllinux
DNS.3 = ordslinux
DNS.4 = notrealsvr
DNS.5 = oramatt.notathing.com

EOF

Regardless of using a specific IP address or localhost, all instructions from this point remain the same.

Next create the required certificate files with our configuration like so:

openssl req -x509 -nodes -days 365 \
  -newkey rsa:2048 \
  -keyout /tmp/self-signed.key \
  -out /tmp/self-signed.pem \
  -config /tmp/ords_cert.cnf \
  -extensions req_ext

Review the generated files for correctness:

openssl x509 -in /tmp/self-signed.pem -text  | grep -A2 "Basic Constraints"

Output should be similar to this:

X509v3 Basic Constraints: critical
CA:TRUE
openssl rsa -in /tmp/self-signed.key -check

Output should be similar to this:

RSA key ok
writing RSA key
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----

3. Copy the files to the ORDS configuration directory

Copy the files to the ORDS ords_config directory and set permissions like so:

cp /tmp/self-signed.pem /home/oracle/ords_config/global/standalone/
cp /tmp/self-signed.key /home/oracle/ords_config/global/standalone/
chmod 600 /home/oracle/ords_config/global/standalone/self-signed.*

4. Configure ORDS to use the Generated Self-Signed Certificate

Apply the configuration settings to enable TLS for MongoDB API using your self-signed certificate:

# ORDS HTTPS settings
/home/oracle/ords/bin/ords --config /home/oracle/ords_config config set standalone.https.cert /home/oracle/ords_config/global/standalone/self-signed.pem
/home/oracle/ords/bin/ords --config /home/oracle/ords_config config set standalone.https.cert.key /home/oracle/ords_config/global/standalone/self-signed.key
/home/oracle/ords/bin/ords --config /home/oracle/ords_config config set standalone.https.host localhost
/home/oracle/ords/bin/ords --config /home/oracle/ords_config config set standalone.https.port 8443

# ORDS MongoDB API settings
/home/oracle/ords/bin/ords --config /home/oracle/ords_config config set mongo.enabled true
/home/oracle/ords/bin/ords --config /home/oracle/ords_config config set mongo.tls true
/home/oracle/ords/bin/ords --config /home/oracle/ords_config config set mongo.port 27017
/home/oracle/ords/bin/ords --config /home/oracle/ords_config config set mongo.access.log mongologs

Review configuration changes:

# ORDS HTTPS settings
/home/oracle/ords/bin/ords --config /home/oracle/ords_config config info standalone.https.cert
/home/oracle/ords/bin/ords --config /home/oracle/ords_config config info standalone.https.cert.key
/home/oracle/ords/bin/ords --config /home/oracle/ords_config config info standalone.https.host
/home/oracle/ords/bin/ords --config /home/oracle/ords_config config info standalone.https.port

# ORDS MongoDB API settings
/home/oracle/ords/bin/ords --config /home/oracle/ords_config config info mongo.enabled
/home/oracle/ords/bin/ords --config /home/oracle/ords_config config info mongo.port
/home/oracle/ords/bin/ords --config /home/oracle/ords_config config info mongo.tls
/home/oracle/ords/bin/ords --config /home/oracle/ords_config config info mongo.access.log

5. Start ORDS

Once configured, start ORDS in standalone mode with HTTPS listening port:

/home/oracle/ords/bin/ords --config /home/oracle/ords_config serve --secure --port 8443

You should see output like the following:

INFO HTTP and HTTP/2 cleartext listening on host: 0.0.0.0 port: 8080
INFO HTTPS listening on host: 0.0.0.0 port: 8443
INFO Oracle API for MongoDB listening on port: 27017

Command for serving ORDS and suppressing stdout/stderr output:

/home/oracle/ords/bin/ords --config /home/oracle/ords_config serve --secure --port 8443 > /dev/null 2>&1 &

ORDS with TLS for the MongoDB API is now correctly configured and running.

6. Connect Using mongosh

MongoDB clients like mongosh expect the server’s TLS certificate to be signed by a trusted Certificate Authority (CA). When using a self-signed certificate with ORDS, the connection will fail unless the client either:

  • Ignores the certificate validation (–tlsAllowInvalidCertificates)
  • Explicitly trusts the certificate by specifying a CA file via –tlsCAFile.

When connecting using mongosh, you’ll need to allow the invalid self-signed cert:

mongosh --tlsAllowInvalidCertificates --verbose \
    "mongodb://matt@localhost:27017/matt?authMechanism=PLAIN&authSource=%24external&tls=true&retryWrites=false&loadBalanced=true"

Replace matt and localhost as needed for your environment.

Using –tlsCAFile is more secure than bypassing validation, especially in test and internal environments where you control the certificate chain. In order to test, transfer the ORDS self-signed.pem file to your client system.

Then connect to the ORDS MongoDB API endpoint like this:

mongosh --tls --tlsCAFile /tmp/self-signed.pem --verbose \
  "mongodb://matt@localhost:27017/matt?authMechanism=PLAIN&authSource=\$external&retryWrites=false&loadBalanced=true"

Replace matt and localhost as needed for your environment.

mongosh --tls --tlsCAFile /tmp/self-signed.pem --verbose \
  "mongodb://matt@10.0.0.78:27017/matt?authMechanism=PLAIN&authSource=\$external&retryWrites=false&loadBalanced=true"

Replace matt and 10.0.0.78 as needed for your environment.

Summary

This guide walks through the configuration setup for ORDS using self-signed certificates for use with the Oracle Database API for MongoDB enabling to quickly test client connections to Oracle Database API for MongoDB with tools from the MongoDB ecosystem.

Notes

  • For production use, consider using certificates from a trusted Certificate Authority (CA).
  • Certificate files should be secured appropriately.
  • This is for non-production demonstrations only.
  • DNS vs IP Address Usage in TLS Certificates
    • When enabling TLS with self-signed certificates, it’s important to understand how clients validate server identity during the TLS handshake. Modern clients, including MongoDB utilities like mongosh, do not rely on the certificate’s Common Name (CN) alone for hostname verification. Instead, they require the presence of a subjectAltName (SAN) extension in the certificate that explicitly lists the DNS names and/or IP addresses the certificate is valid for.In this runbook, we define SAN values using the [alt_names] section of a custom OpenSSL configuration file (ords_cert.cnf). This file is used during certificate generation to ensure compatibility with MongoDB tools:[alt_names] IP.1 = 10.0.0.78 DNS.1 = localhost DNS.2 = orcllinux DNS.3 = ordslinux DNS.4 = notrealsvr DNS.5 = oramatt.notathing.comThis configuration allows connections to succeed whether clients connect using localhost,the IP address 10.0.0.78, or using an alias that is resolved either by /etc/hosts or DNS. By including both types of SAN entries, the self-signed certificate can be validated successfully in a broader set of environments, including development machines, containerized deployments, and static IP setups, without triggering TLS verification errors.Failing to include the appropriate SAN entries can result in errors such as:
      • self-signed certificate
      • unable to verify the first certificate
      • hostname/IP does not match certificate alt names
      Including both DNS and IP entries in the SAN ensures a reliable and secure connection experience during development and testing. This practice is ONLY recommended when generating self-signed certificates for internal use or demonstrations.

Questions/problems/errors/need help

Let me know!

References

Converting a Private Key to DER (Linux and Unix)

Enabling and Configuring the Oracle Database API for MongoDB

Installing and Configuring Customer Managed ORDS on Autonomous Database

Deploying and Monitoring Oracle REST Data Services

Leave a Reply

Discover more from OraMatt: YABAOracle

Subscribe now to keep reading and get access to the full archive.

Continue reading