[how-to] Set Retool on-prem to connect to External API with SSL/TLS

Retool Tips & Tricks
1

This is a brief introduction to how:

  • Retool on-prem/self-hosted instance connects to an external API that uses SSL/TLS certification
  • How to set up Retool on-prem to accept the External API's certificate.

Scenario: User's external API uses self-signed certificate, and Retool is throwing an error:
Error: self signed certificate in certificate chain

What's happening behind the in the backend:

  1. User triggers query within an app making a request to the API
  2. Query is sent from the app's frontend to the Retool's db-connector backend
  3. db-connector makes query request to API endpoint
  4. API sends a certificate that’s self-signed back to db-connector
  5. Retool goes up the certificate chain, and never finds a certificate it knows to trust (like from a certificate authority)
  6. Retool returns an error: self-signed certificate

How to allow Retool to accept API’s self-signed certificate:

Create a Mount for API certificates:

  1. In the retool-onpremise directory, create a certs directory if it doesn't exist.
  2. Add your API certificate to the certs directory in a pem file
  • This file can be a concatenated list of self-signed certificates

  1. Add a mount from the path on the host to the db-connector container. For example with docker-compose, this would look like:
    Screen Shot 2023-03-17 at 2.26.31 PM
    Point db-connector to your API certifications

  2. Enter your db-connector

  3. Open docker.env

  4. Add the environment variable NODE_EXTRA_CA_CERT and set the value to the path of your certificate file (from the container’s perspective, e.g. /retool_backend/certs/cert.pem).

  5. Restart your containers for the changes to take effect

One method of creating a certification from your API:

Within your instance, run:

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 365

IMPORTANT: Make sure your Common Name (CN) matches your Retool instance’s domain or subdomain. If this doesn’t match you will receive an altname error. For example, for retool.domain.com, then the CN should match that or .domain.com.*

7 Likes
2

Extra notes:

  • [REST APIs] - we've since added a custom certificate configuration to the REST API resource. So you can just enter your certificates in the resource during the creation, which makes this available on Cloud as well.
    Self-hosted note: You'd still want to go the environment variable/volume mount route if the certificates are going to be used in a lot of resources, so you don't have to re-enter them every time during Resource creation, or if you want apps to be able to use the resource-less RESTQuery API queries from within the app.
  • [Wildcard] - The domain or a matching wildcard will need to be listed in the Common Name(CN) (only one allowed per cert) or Subject Alternative Name(SAN) (allows multiple) attributes of the cert (e.g. retool.com and/or *. retool.com)