Skip to main content

Agent TLS Termination

Agent TLS termination enables you to secure your traffic with end-to-end encryption without needing to reconfigure your server.

tip

If your service doesn't support TLS termination, you can still use Agent TLS termination with Zero-Knowledge TLS.

Quickstart​

The following instructions will guide you through setting up Agent TLS termination with ngrok.

Prerequisites​

Step 1 – Generate a cert and key pair​

The following command:

  1. Generates a new certificate signing request (CSR) for a 4096-bit RSA key pair.
    • The key is saved to your-key.key.
  2. Creates a self-signed certificate which:
    • Is in x509 format and uses the SHA-256 hash algorithm.
    • Is valid for 365 days.
    • Is saved to your-cert.crt.
Loading…

Step 2 – Configure your endpoint​

You can configure your endpoint with an agent configuration file. To create a new configuration file with your generated cert and key pair, run the following command:

Loading…

Your generated configuration file should resemble the following:

Loading…
tip

You can run ngrok config edit to open the configuration file in your default text editor. Learn more about the ngrok config command.

Step 3 – Start your endpoint​

Next, use ngrok start endpoint_name_here in the terminal to start an endpoint using the settings in your agent configuration file, as shown below:

Loading…

Step 4 – Start your upstream server​

Start an upstream server on the specified port (e.g., 12345) to handle incoming requests. The following example uses Python, but you can use any language or framework depending on your requirements.

Loading…

Step 5 – Try connecting to your endpoint​

The following example uses openssl s_client to initiate an SSL/TLS client connection to your upstream server without a certificate.

Loading…
Loading…

The following example uses openssl s_client to initiate an SSL/TLS client connection to your upstream server with a certificate.

Loading…
Loading…
note

The extra arguments added to the command suppress most of the output so that only the data exchanged with the server will be displayed.

Mutual TLS example​

The following instructions will guide you through setting up Agent TLS termination using Mutual TLS (mTLS) with ngrok.

Step 1 – Generate a root CA private key and certificate​

Loading…

Step 2 – Generate server credentials​

The following terminal commands will generate these server credentials:

  • A server private key
  • A CSR
  • A signed certificate
Loading…

Step 3 – Generate client credentials​

The following terminal command will generate these client credentials:

  • A private key
  • A CSR
  • A signed certificate
Loading…

Step 4 – Configure your mTLS endpoint​

Use the following command to create an agent configuration file with your generated certificates:

Loading…

Your generated configuration file should resemble the following:

Loading…

Step 5 – Start your mTLS endpoint​

Next, use ngrok start endpoint_name_here in the terminal to start an endpoint using the settings in your agent configuration file, as shown below:

Loading…

Step 6 – Start your upstream server​

Start an upstream server on the specified port (e.g., 12345) to handle incoming requests. The following example uses Python, but you can use any language or framework depending on your requirements.

Loading…

Step 7 – Try connecting to your mTLS endpoint​

The following example uses openssl s_client to initiate an SSL/TLS client connection to your upstream server without a certificate.

Loading…
Loading…

The following example uses openssl s_client to initiate an SSL/TLS client connection to your upstream server with a certificate.

Loading…
Loading…