TLS Termination

Overview

This module enables you to configure TLS termination at either your upstream service, the ngrok edge or the ngrok agent. It also allows you to configure the parameters of that termination.

By default, TLS endpoints terminate TLS connections at your upstream service. This means that by default, ngrok does not terminate TLS connections, your upstream service must handle TLS termination.

Terminating TLS at the ngrok edge is a good choice in the following circumstances:

• You want ngrok to automatically manage TLS certificate provisioning for you.
• You want ngrok to enforce Mutual TLS. TLS Termination is required to enforce mTLS.
• You want to accelerate TLS termination by executing it at ngrok's edge, closer to your clients
• Your upstream service can't terminate TLS. This is common for legacy software.

Example Usage

Terminate at upstream service

Agent CLI

ngrok tls 443 \
  --terminate-at upstream \
  --url app.example.com

Agent Config

tunnels:
  example:
    proto: tls
    domain: app.example.com
    addr: 443
    terminate_at: upstream

SSH

ssh -R app.example.com:443:localhost:443 v2@connect.ngrok-agent.com tls

Go

import (
        "context"
        "net"

        "golang.ngrok.com/ngrok"
        "golang.ngrok.com/ngrok/config"
)

func ngrokListener(ctx context.Context) (net.Listener, error) {
        return ngrok.Listen(ctx,
                config.TLSEndpoint(
                        config.WithDomain("app.example.com"),
                ),
                ngrok.WithAuthtokenFromEnv(),
        )
}

Go Package Docs:

• https://pkg.go.dev/golang.ngrok.com/ngrok/config#TLSEndpoint

Javascript

const ngrok = require("@ngrok/ngrok");

(async function () {
	const listener = await ngrok.forward({
		addr: 8080,
		authtoken_from_env: true,
		proto: "tls",
		domain: "app.example.com",
	});

	console.log(`Ingress established at: ${listener.url()}`);
})();

Javascript SDK Docs:

• https://ngrok.github.io/ngrok-javascript/interfaces/Config.html#domain
• https://ngrok.github.io/ngrok-javascript/classes/TlsListenerBuilder.html#domain

Python

import ngrok

listener = ngrok.forward("localhost:8080", authtoken_from_env=True,
    proto="tls",
    domain="app.example.com")

print(f"Ingress established at: {listener.url()}");

Python SDK Docs:

• https://ngrok.github.io/ngrok-python/tls_listener_builder.html#ngrok.TlsListenerBuilder.domain
• https://ngrok.github.io/ngrok-python/index.html#full-configuration

Rust

use ngrok::prelude::*;

async fn listen_ngrok() -> anyhow::Result<impl Tunnel> {
    let sess = ngrok::Session::builder()
        .authtoken_from_env()
        .connect()
        .await?;

    let tun = sess
        .tls_endpoint()
        .domain("app.example.com")
        .listen()
        .await?;

    println!("Listening on URL: {:?}", tun.url());

    Ok(tun)
}

Rust Crate Docs:

• https://docs.rs/ngrok/latest/ngrok/config/struct.TlsTunnelBuilder.html#method.domain

Kubernetes Controller

info

TLS endpoints are not supported by the Kubernetes Ingress Controller

Terminate at ngrok edge

Agent CLI

ngrok tls 80 --terminate-at edge

Agent Config

tunnels:
  example:
    proto: tls
    addr: 80
    terminate_at: edge

SSH

info

SSH does not support termination at the edge

Go

import (
        "context"
        "net"

        "golang.ngrok.com/ngrok"
        "golang.ngrok.com/ngrok/config"
)

func ngrokListener(ctx context.Context) (net.Listener, error) {
        return ngrok.Listen(ctx,
                config.TLSEndpoint(
                        config.WithTLSTermination(
                                config.WithTLSTerminationAt(config.TLSAtEdge),
                        ),
                ),
                ngrok.WithAuthtokenFromEnv(),
        )
}

Go Package Docs:

• https://pkg.go.dev/golang.ngrok.com/ngrok/config#WithTLSTermination
• https://pkg.go.dev/golang.ngrok.com/ngrok/config#WithTLSTerminationAt

Javascript

const ngrok = require("@ngrok/ngrok");

(async function () {
	const listener = await ngrok.forward({
		addr: 8080,
		authtoken_from_env: true,
		proto: "tls",
		crt: "",
		key: "",
	});

	console.log(`Ingress established at: ${listener.url()}`);
})();

An empty certificate and key will default to the ngrok edge's automatically provisioned keypair.

Javascript SDK Docs:

• https://ngrok.github.io/ngrok-javascript/classes/TlsListenerBuilder.html
• https://ngrok.github.io/ngrok-javascript/classes/Session.html#tlsEndpoint
• https://ngrok.github.io/ngrok-javascript/interfaces/Config.html#proto

Python

import ngrok

listener = ngrok.forward("localhost:8080", authtoken_from_env=True,
    proto="tls"
    crt=bytearray(),
    key=bytearray())

print(f"Ingress established at: {listener.url()}");

An empty certificate and key will default to the ngrok edge's automatically provisioned keypair.

Python SDK Docs:

• https://ngrok.github.io/ngrok-python/tls_listener_builder.html#ngrok.TlsListenerBuilder.termination
• https://ngrok.github.io/ngrok-python/index.html#full-configuration

Rust

use ngrok::prelude::*;

async fn listen_ngrok() -> anyhow::Result<impl Tunnel> {
    let sess = ngrok::Session::builder()
        .authtoken_from_env()
        .connect()
        .await?;

    let tun = sess
        .tls_endpoint()
        .termination(Bytes::new(), Bytes::new())
        .listen()
        .await?;

    println!("Listening on URL: {:?}", tun.url());

    Ok(tun)
}

An empty certificate and key will default to the ngrok edge's automatically provisioned keypair.

Rust Crate Docs:

• https://docs.rs/ngrok/latest/ngrok/session/struct.Session.html#method.tls_endpoint

Kubernetes Controller

info

TLS endpoints are not supported by the Kubernetes Ingress Controller

Terminate at ngrok agent

Agent CLI

ngrok tls 80 \
  --terminate-at agent \
  --url app.example.com \
  --crt /path/to/app-example-com-crt.pem \
  --key /path/to/app-example-com-key.pem

Agent Config

tunnels:
  example:
    proto: tls
    terminate_at: agent
    domain: app.example.com
    addr: 80
    crt: /path/to/app-example-com-crt.pem
    key: /path/to/app-example-com-key.pem

SSH

info

SSH does not support termination at the agent

Go

info

The Go SDK does not support TLS termination at the SDK

Javascript

info

The Javascript SDK does not support TLS termination at the SDK.

Python

info

The Python SDK does not support TLS termination at the SDK.

Rust

info

The Rust SDK does not support TLS termination at the SDK.

Kubernetes Controller

info

TLS endpoints are not supported by the Kubernetes Ingress Controller

Custom cert at ngrok edge

Agent CLI

ngrok tls 80
  --url your-name.ngrok.app \
  --terminate-at edge \
  --crt /path/to/app-example-com-crt.pem \
  --key /path/to/app-example-com-key.pem

Agent Config

tunnels:
  example:
    proto: tls
    terminate_at: edge
    domain: app.example.com
    addr: 80
    crt: /path/to/app-example-com-crt.pem
    key: /path/to/app-example-com-key.pem

SSH

info

SSH does not support termination at the edge

Go

import (
        "context"
        "net"

        "golang.ngrok.com/ngrok"
        "golang.ngrok.com/ngrok/config"
)

func ngrokListener(ctx context.Context) (net.Listener, error) {
	crtBytes := os.ReadFile("/path/to/app-example-com-crt.pem")
	keyBytes := os.ReadFile("/path/to/app-example-com-key.pem")
        return ngrok.Listen(ctx,
                config.TLSEndpoint(
                        config.WithDomain("example.ngrok.app"),
                        config.WithTLSTermination(
                                config.WithTLSTerminationAt(config.TLSAtEdge),
                                config.WithTLSTerminationKeyPair(certBytes, keyBytes),
                        ),
                ),
                ngrok.WithAuthtokenFromEnv(),
        )
}

Go Package Docs:

• https://pkg.go.dev/golang.ngrok.com/ngrok/config#WithTLSTerminationKeyPair

Javascript

const ngrok = require("@ngrok/ngrok");
const fs = require("fs");

(async function () {
	const listener = await ngrok.forward({
		addr: 8080,
		authtoken_from_env: true,
		proto: "tls",
		crt: fs.readFileSync("/path/to/app-example-com-crt.pem", "utf8"),
		key: fs.readFileSync("/path/to/app-example-com-key.pem", "utf8"),
	});

	console.log(`Ingress established at: ${listener.url()}`);
})();

Javascript SDK Docs:

• https://ngrok.github.io/ngrok-javascript/interfaces/Config.html#crt
• https://ngrok.github.io/ngrok-javascript/interfaces/Config.html#key
• https://ngrok.github.io/ngrok-javascript/classes/TlsListenerBuilder.html#termination

Python

import ngrok

def load_file(name):
    with open(name, "r") as crt:
        return bytearray(crt.read().encode())

listener = ngrok.forward("localhost:8080", authtoken_from_env=True,
    proto="tls",
    crt=load_file("/path/to/app-example-com-crt.pem"),
    key=load_file("/path/to/app-example-com-key.pem"))

print(f"Ingress established at: {listener.url()}");

Python SDK Docs:

• https://ngrok.github.io/ngrok-python/tls_listener_builder.html#ngrok.TlsListenerBuilder.termination
• https://ngrok.github.io/ngrok-python/index.html#full-configuration

Rust

use ngrok::prelude::*;

async fn listen_ngrok() -> anyhow::Result<impl Tunnel> {
    let cert: &[u8] = load_bytes!("/path/to/app-example-com-crt.pem");
    let key: &[u8] = load_bytes!("/path/to/app-example-com-key.pem");

    let sess = ngrok::Session::builder()
        .authtoken_from_env()
        .connect()
        .await?;

    let tun = sess
        .tls_endpoint()
        .domain("app.example.com")
        .termination(cert.into(), key.into())
        .termination(
        .listen()
        .await?;

    println!("Listening on URL: {:?}", tun.url());

    Ok(tun)
}

Rust Crate Docs:

• https://docs.rs/ngrok/latest/ngrok/session/struct.Session.html#method.tls_endpoint

Kubernetes Controller

info

TLS endpoints are not supported by the Kubernetes Ingress Controller

Behavior

Certificates

The following section will help you resolve any certificate errors you run into while using TLS termination. Because TLS endpoints are flexible enough to terminate TLS at either the ngrok edge, the ngrok agent or your upstream service, you may encounter certificate errors. Understanding how the ngrok platform handles certificates can help resolve them quickly.

When you terminate TLS at the ngrok edge, you may choose between bringing your own certificates and allowing ngrok to automatically provision certificates for you from an ACME provider like Let's Encrypt. If you use automatic certificates, ngrok will choose a matching, valid certificate for you and it will provision and renew that, if necessary. This works even if you're listening on a randomly-chosen ngrok domain.

When using Zero-Knowledge TLS by terminating at the ngrok agent or at your upstream service, you should always specify a domain. If you don't specify a domain to listen on, you won't have already provisioned a signed certificate for that domain. Make sure that the certificate you're using exactly matches the name of the domain you've asked ngrok to listen on.

Zero-Knowledge TLS

When TLS is not terminated at the ngrok edge, then your TLS connections are end-to-end encrypted (E2EE) which we call Zero-Knowledge TLS. When your TLS endpoints operate in this mode, the ngrok edge can not see the payloads that transfer through your endpoints.

The ngrok edge enables Zero-Knowledge TLS by using the SNI data of incoming TLS connections to route them to the proper endpoint without terminating TLS. The unterminated connections are forwarded all the way through to your upstream application which is then responsible for TLS termination.

Zero-Knowledge TLS at the Agent

If the service you are exposing does not support TLS termination, you can still take advantage of Zero-Knowledge TLS. The ngrok agent can terminate TLS for you allowing you to encrypt your traffic end-to-end without reconfiguring your upstream service. This is often a good choice if your upstream service is a piece of legacy software that doesn't support TLS or if it's operated out of your control.

Specify --terminate-at agent with both the --crt and --key command-line options when starting the agent to specify the filesystem paths to your TLS certificate and key and the ngrok agent will take care of terminating TLS connections for you.

TLS Version Choice

If you configure ngrok to do TLS termination, either at the edge or in the agent, it will prefer to use TLS 1.3 if the client supports it.

When terminating at the ngrok edge, a minimum supported version of TLS 1.2 is chosen by default. Clients that do not support TLS 1.2 will not be able to connect. This value is configurable when using Edges.

When terminating at the ngrok agent, a minimum supported version of TLS 1.2 is chosen by default. Clients that do not support TLS 1.2 will not be able to connect. This value is not configurable.

Reference

Configuration

Parameter	Default	Description
Terminate At	upstream	Where to terminate TLS. One of: edge, upstream, agent
Minimum TLS Version	1.2	The minimum version of TLS to negotiate. Clients which do not support at least this version of TLS will be unable to connect.

Errors

This module does not return any errors.

Events

No event data is captured for this module on TLS endpoints.

Edges

TLS Termination is a supported TLS Edge module.

• TLS Termination Edge Module API Resource

Pricing

This module is available on the Enterprise plan.

Try it out

Coming Soon

This documentation is incomplete. Please check back later, we appreciate your patience.