Mutual TLS

Overview

This module performs mutual TLS (mTLS) authentication for your TLS endpoints. The client must present a valid TLS certificate that is signed by one of the specified CAs or the connection will be rejected.

Mutual TLS can only be enforced where TLS is terminated. This means ngrok's Mutual TLS module may only be used where you also use ngrok to terminates TLS on your behalf. You may choose whether Mutual TLS is enforced at ngrok's edge or in the ngrok agent.

Example Usage

Remember that by default, TLS endpoints do not terminate TLS connections and send them through to your upstream service. Thus, all examples you see for mutual TLS will also include TLS termination.

mTLS at ngrok edge

Only allow connections which present a client certificate signed by one of the CAs present in the PEM bundle.

ngrok tls 80 \
  --domain app.example.com \
  --terminate-at edge \
  --mutual-tls-cas /path/to/cas.pem

tunnels:
  example:
    proto: "tls"
    addr: 80
    domain: "app.example.com"
    terminate_at: "edge"
    mutual_tls_cas: "/path/to/cas.pem"

import (
	"context"
	"crypto/x509"
	"encoding/pem"
	"net"
	"os"

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

func ngrokListener(ctx context.Context) (net.Listener, error) {
	caBytes, _ := os.ReadFile("/path/to/cas.pem")
	der, _ := pem.Decode(caBytes)
	certs, _ := x509.ParseCertificates(der.Bytes)

	return ngrok.Listen(ctx,
		config.TLSEndpoint(
			config.WithDomain("app.example.com"),
			config.WithTLSTermination(
				config.WithTLSTerminationAt(config.TLSAtEdge),
			),
			config.WithMutualTLSCA(certs...),
		),
		ngrok.WithAuthtokenFromEnv(),
	)
}

Go Package Docs:

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

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"),
		mutual_tls_cas: [fs.readFileSync("/path/to/cas.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"),
	mutual_tls_cas=load_file("/path/to/cas.pem"))

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

Python SDK Docs:

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 ca_cert: &[u8] = load_bytes!("/path/to/cas.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())
        .mutual_tlsca(ca_cert.into())
        .listen()
        .await?;

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

    Ok(tun)
}

Rust Crate Docs:

mTLS at ngrok agent

Mutual TLS enforcement at the ngrok agent is used with Zero-Knowledge TLS end-to-end encryption.

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

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

Behavior

Multiple CAs

You may specify multiple CAs to be used for mTLS authentication. A connection is considered authenticated if it presents a certificate signed by any of the specified CAs. Agents allow you to specify multiple CAs by simply specifying a PEM file that contains multiple x509 CA certificates concatenated together. A file like that might look like:

-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----

CA Basic Constraint

x509 certificates contain a basic constraint attribute called cA which defines whether or not the certificate may be used as a CA.

ngrok will refuse to accept a certificate as an mTLS certificate authority unless this constraint is set to true.

See RFC 5280 4.2.1.9.

Reference

Configuration

Agent Configuration

Parameter	Description
Certificate Authorities	PEM-encoded certificate authorities. You may concatenate CAs to multiple together. A client certificate must be signed by at least one of the CAs.

Edge Configuration

Parameter	Description
Certificate Authority IDs	A set of certificates authorities. A client certificate must be signed by at least one of the configured CAs. See the TLS Edge Mutual TLS Module API Resource for additional details. Max of 10.

Errors

If the client does not present any certificate or it does not present a valid certificate signed by the CA, the TLS handshake will be aborted.

The TLS connection aborts with a TLS error as defined by RFC 5246. The most common alert code returned for a failed mutual TLS handshake is code 42 (bad_certificate) which most TLS implementations will report with the error string string "bad certificate".

Events

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

Edges

Mutual TLS is a supported Edge module. When the Mutual TLS module is configured via an Edge, you must specify one or more references to Certificate Authority objects.

Pricing

This module is available on the Enterprise plan.

Try it out

This example assumes you have an x509 private key and certificate encoded as PEM files called client-key.pem and client-cert.pem, respectively. The certificate must be signed by one of the CA certificates you provided to the Mutual TLS module.

Run curl with the following command:

curl --client client-cert.pem --key client-key.pem https://yourapp.ngrok.app

curl has a shortcut to pass a single file if the private key and certificate are concatenated together.

cat client-cert.pem client-key.pem > client-cert-and-key.pem
curl --cert client-cert-and-key.pem https://yourapp.ngrok.app

Mutual TLS

Overview​

Example Usage​

mTLS at ngrok edge​

mTLS at ngrok agent​

Behavior​

Multiple CAs​

CA Basic Constraint​

Reference​

Configuration​

Agent Configuration​

Edge Configuration​

Errors​

Events​

Edges​

Pricing​

Try it out​