Agent TLS Termination

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

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

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

What you’ll need

Ensure you have openssl installed.

1. Generate a cert and key pair

The following command:

Generates a new certificate signing request (CSR) for a 4096-bit RSA key pair.
- The key is saved to your-key.key.
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.

openssl req -new -newkey rsa:4096 -x509 -sha256 -days 365 -noenc -out your-cert.crt -keyout your-key.key

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:

ngrok config add-authtoken you-authtoken

Your generated configuration file should resemble the following:

version: 3
agent:
  authtoken: your-authtoken
endpoints:
  - name: demo-tls
    url: tls://your-domain.ngrok.app
    upstream:
      url: 12345
    agent_tls_termination:
      server_certificate: /path/to/your-cert.crt
      server_private_key: /path/to/your-key.key

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

Optional: require client certificates (mTLS) at the agent

To make the agent authenticate clients as part of the TLS handshake, add one or more Certificate Authorities to the agent_tls_termination block with mutual_tls_certificate_authorities. The agent will reject any client whose certificate isn’t signed by one of the listed CAs.

version: 3
agent:
  authtoken: your-authtoken
endpoints:
  - name: demo-tls
    url: tls://your-domain.ngrok.app
    upstream:
      url: 12345
    agent_tls_termination:
      server_certificate: /path/to/your-cert.crt
      server_private_key: /path/to/your-key.key
      mutual_tls_certificate_authorities:
        - /path/to/your-ca-cert.crt

See agent_tls_termination.mutual_tls_certificate_authorities for the full reference.

This is different from mTLS terminated at the ngrok edge via the terminate-tls Traffic Policy action. With agent-side mTLS, the client certificate is validated by your agent; traffic between the ngrok edge and your agent is still carried over the agent’s secure TLS connection to ngrok, but client-certificate authentication is not performed on that hop.

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:

ngrok start demo-tls

4. Start your upstream server

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

import socket

host='127.0.0.1'
port=12345
server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
server.bind((host, port))
print(f"Server started on {host}:{port}")
server.listen(1)

while True:
    client, client_address = server.accept()
    print(f"Connection established with {client_address}")
    client.sendall(b"hello, world!")
    client.close()
    print(f"Connection with {client_address} closed")

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.

openssl s_client -quiet -connect your-domain.ngrok.app:443 -verify_return_error

Connecting to 2600:1f16:d83:1200::6e:0
depth=0 C=AU, ST=Some-State, O=Internet Widgets Pty Ltd, CN=your-domain.ngrok.app
verify error:num=18:self-signed certificate
408FB6F801000000:error:0A000086:SSL routines:tls_post_process_server_certificate:certificate verify failed:ssl/statem/statem_clnt.c:2093:

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

openssl s_client -quiet -connect your-domain.ngrok.app:443 -verify_return_error -CAfile your-cert.crt

Connecting to 2600:1f16:d83:1200::6e:0
depth=0 C=AU, ST=Some-State, O=Internet Widgets Pty Ltd, CN=your-domain.ngrok.app
verify return:1
hello, world!%

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

Observing Agent Traffic

CLI

CLI Configuration File

Reference

Guides

Agent TLS Termination

What you’ll need

1. Generate a cert and key pair

2. Configure your endpoint

Optional: require client certificates (mTLS) at the agent

3. Start your endpoint

4. Start your upstream server

5. Try connecting to your endpoint

​What you’ll need

​1. Generate a cert and key pair

​2. Configure your endpoint

​Optional: require client certificates (mTLS) at the agent

​3. Start your endpoint

​4. Start your upstream server

​5. Try connecting to your endpoint

What you’ll need

1. Generate a cert and key pair

2. Configure your endpoint

Optional: require client certificates (mTLS) at the agent

3. Start your endpoint

4. Start your upstream server

5. Try connecting to your endpoint