Mutual TLS
Overview
This module performs mutual TLS (mTLS) authentication when the ngrok edge terminates TLS on incoming connections to your HTTP endpoint. The client must present a valid TLS certificate that is signed by one of the specified CAs or the connection will be rejected.
ngrok injects headers into upstream HTTP requests with information about the client certificate presented.
Example Usage
Only allow requests whose connections present a client certificate signed by one of the CAs present in the PEM bundle.
- Agent CLI
- Agent Config
- SSH
- Go
- Javascript
- Python
- Rust
- Kubernetes Controller
ngrok http 80 --mutual-tls-cas /path/to/cas.pem
tunnels:
example:
proto: "http"
addr: 80
mutual_tls_cas: "/path/to/cas.pem"
Mutual TLS is not supported via SSH.
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.HTTPEndpoint(
config.WithMutualTLSCA(certs...),
),
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,
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,
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 ca_cert: &[u8] = load_bytes!("/path/to/cas.pem");
let sess = ngrok::Session::builder()
.authtoken_from_env()
.connect()
.await?;
let tun = sess
.http_endpoint()
.mutual_tlsca(ca_cert.into())
.listen()
.await?;
println!("Listening on URL: {:?}", tun.url());
Ok(tun)
}
Rust Crate Docs:
Mutual TLS is not yet supported with the Kubernetes Ingress Controller.
You can +1 the GitHub issue tracking its implementation.
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 HTTPS Edge Mutual TLS Module API Resource for additional details. Max of 10. |
Upstream Headers
This module adds headers to the HTTP request sent to your upstream service with details about the client certificate that was presented for the Mutual TLS handshake.
Header Name | Value |
---|---|
ngrok-mtls-subject-cn | The client certificate subject common name |
ngrok-mtls-subject-alt-name-dns | The client certificate's DNS subject alternative names |
ngrok-mtls-email-addresses | The client certificate's email subject alternative names |
ngrok-mtls-serial-number | The client certificate's serial number |
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. Because the connection is aborted during the TLS handshake, the client will not receive an HTTP error response or an ngrok error code.
Instead, 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
When the mutual TLS module is enabled, it populates the following fields in http_request_complete.v0 events.
Fields |
---|
tls.client_cert.serial_number |
tls.client_cert.subject.cn |
No event data is captured when the module is enabled on TLS endpoints.
Edges
Mutual TLS is an HTTPS Edge module. When the Mutual TLS module is configured via an Edge, you must specify one or more references to Certificate Authority objects.
The Mutual TLS Edge module is applied to the Edge directly and not to any individual Route. This is because Mutual TLS is enforced before any HTTP processing can begin.
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