TLS Endpoints

Overview

TLS endpoints enable you to deliver any network service that runs over a TLS-based protocol. TLS endpoints make no assumptions about the wrapped protocol being transported.

TLS endpoints inspect the Server Name Indication (SNI) data on incoming TLS connections to route connections to the appropriate endpoint.

Because the TLS protocol describes no application-level semantics, ngrok can only offer a limited set of traffic policy actions to handle TLS traffic.

If you are delivering an HTTPS application, prefer to create an HTTP Endpoint.

Quickstart

Agent Endpoint

ngrok tls 80 --terminate-at edge --url your-name.ngrok.app

tunnels:
  example:
    proto: tls
    terminate_at: edge
    domain: your-name.ngrok.app
    addr: 80

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("your-name.ngrok.app"),
                        config.WithTLSTermination(
                                config.WithTLSTerminationAt(config.TLSAtEdge),
                        ),
                ),
                ngrok.WithAuthtokenFromEnv(),
        )
}

Go Package Docs:

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

(async function () {
	const listener = await ngrok.forward({
		addr: 8080,
		authtoken_from_env: true,
		proto: "tls",
		domain: "app.example.com",
		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:

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",
    domain="app.example.com",
    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:

Cloud Endpoint

TODO

URLs

URLs are validated differently depending on their binding. Consult the following documentation for details on valid URLs for TLS endpoints:

There is no standard scheme for TLS URLs so ngrok renders them as tls://.

Bindings

TLS endpoints support public and internal bindings. kubernetes binding is not supported.

Traffic Policy

Attach Traffic Policy to endpoints to route, authenticate and transform the traffic through your TLS endpoints.

Authentication

When you create public TLS endpoints, you often want to secure them with authentication. You can secure your TLS endpoints with the following Traffic Policy actions. There is a limited set of actions available to authenticate TLS traffic because the TLS protocol is low-level.

TLS

Termination

TLS Endpoints provide you with the flexibility to define where TLS termination occurs. You may configure your endpoint to terminate TLS at the ngrok cloud service or you can achieve end-to-end encryption by terminating at the agent or your upstream service. When you use end-to-end encryption, the ngrok cloud service can not see payload that transit through your endpoints.

Consult the documentation on TLS Termination Locations for additional details.

Cloud Service

ngrok tls 80 --terminate-at edge --url your-name.ngrok.app

tunnels:
  example:
    proto: tls
    terminate_at: edge
    domain: your-name.ngrok.app
    addr: 80

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("your-name.ngrok.app"),
                        config.WithTLSTermination(
                                config.WithTLSTerminationAt(config.TLSAtEdge),
                        ),
                ),
                ngrok.WithAuthtokenFromEnv(),
        )
}

Go Package Docs:

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

(async function () {
	const listener = await ngrok.forward({
		addr: 8080,
		authtoken_from_env: true,
		proto: "tls",
		domain: "app.example.com",
		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:

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",
    domain="app.example.com",
    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:

Terminate at Agent

See Zero-Knowledge TLS at the Agent for additional details.

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

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

Terminate at Upstream

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

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

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

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

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:

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:

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

Certificates

It is very common to encounter certificate errors when working with TLS endpoints. When terminating TLS at ngrok's cloud service, ngrok will automatically select, provision and manage certs for you. When performing end-to-end encryption by terminating at the agent or upstream service, you become responsible for provisioning, managing and distributing certificates.

Consult the documentation on TLS Certificates for details about certificate selection, provisioning and management.

Agent Forwarding

Re-encrypt to Upstream

If you terminate TLS at the ngrok cloud service or ngrok agent, you may want to re-encrypt the connection from the agent to your upstream service. The ngrok agent supports this behavior by using the non-standard tls:// scheme syntax.

ngrok tls tls://localhost:443 --terminate-at=edge

tunnels:
  example:
    proto: tls
    addr: tls://localhost:443
    terminate_at: edge

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

(async function () {
	const listener = await ngrok.forward({
		addr: "tls://localhost:443",
		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. The upstream certificate of localhost:443 will be validated by a filepath specified in the SSL_CERT_FILE environment variable (e.g. SSL_CERT_FILE=/path/to/ca.crt), or falling back to the host OS installed trusted certificate authorities.

Javascript SDK Docs:

import ngrok

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

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

Python SDK Docs:

PROXY Protocol

Add a PROXY protocol header on connection to your upstream service. This sends connection information like the original client IP address to your upstream service.

ngrok tls 443 --upstream-proxy-protocol=2

tunnels:
  example:
    proto: tls
    addr: 443
    proxy_protocol: 2

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.WithProxyProto(2),
		),
		ngrok.WithAuthtokenFromEnv(),
	)
}

Go Package Docs:

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

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

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

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

Javascript SDK Docs:

import ngrok

listener = ngrok.forward("localhost:8080", authtoken_from_env=True,
    proto="tls",
    proxy_proto="2")

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

Python SDK Docs:

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()
        .proxy_proto(ProxyProto::V2)
        .listen()
        .await?;

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

    Ok(tun)
}

Rust Crate Docs:

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

Compatible Clients

SNI

TLS endpoints only work with modern TLS clients that populate the SNI extension. See the documentation on TLS Termination for additional details on compatible clients.

STARTTLS

Protocols that begin in plain text and upgrade to TLS via a mechanism like STARTTLS in SMTP, IMAP, etc are not supported. If you need to support connections which upgrade to TLS, use a TCP Endpoint.

Observability

Traffic Inspector

Traffic Inspector does not support TLS endpoints.

Log Export Events

You can export logs of traffic to TLS endpoints with ngrok's events system. The following events are published for log exporting:

Event	When
tcp_connection_closed.v0	Published when a TCP connection to a TCP endpoint completes.

API

TLS Endpoints can be created programatically. Consult the documentation on Endpoint APIs.

Errors

If a TLS handshake fails, an appropriate TLS abort code will be sent to the client.

In all other cases, if an error is encountered while handling TLS connections to your endpoints (e.g. no available backends or internal server error), the connection will be closed. The TLS protocol and its implementations are not sufficiently flexible enough to deliver additional rich error information when failures are encountered.

Use the observability features to understand connection handling errors.

Pricing

TLS endpoints are available on Pay-as-you-go, Pro, and Enterprise plans. Consult the Endpoints Pricing documentation for billing details.

See Domains pricing for details on pricing for custom domains, wildcard domains and more.

Zero-knowledge TLS is available on the Enterprise plan.

Overview​

Quickstart​

Agent Endpoint​

Cloud Endpoint​

URLs​

Bindings​

Traffic Policy​

Authentication​

TLS​

Termination​

Cloud Service​

Terminate at Agent​

Terminate at Upstream​

Certificates​

Agent Forwarding​

Re-encrypt to Upstream​

PROXY Protocol​

Compatible Clients​

SNI​

STARTTLS​

Observability​

Traffic Inspector​

Log Export Events​

API​

Errors​

Pricing​

Overview

Quickstart

Agent Endpoint

Cloud Endpoint

URLs

Bindings

Traffic Policy

Authentication

TLS

Termination

Cloud Service

Terminate at Agent

Terminate at Upstream

Certificates

Agent Forwarding

Re-encrypt to Upstream

PROXY Protocol

Compatible Clients

SNI

STARTTLS

Observability

Traffic Inspector

Log Export Events

API

Errors

Pricing