How to implement mutual TLS (mTLS) with ngrok’s API gateway
By Joel Hans
August 13, 2024
By Joel Hans
August 13, 2024
04-23-2025: We updated this blog post with information about our new
terminate-tlsTraffic Policy action, which makes adding mTLS at your API gateway even easier and more composable.
When developing services that require mutual TLS (mTLS) with an API gateway, your infrastructure and certificate management challenges start mounting straightaway. It’s hard to set up the proper local environment to test how your API responds to an mTLS implementation, and once you do, that environment rarely carries over to your production infrastructure.
You need to protect the data made available on your API, whether you’re dealing with Internet of Things (IoT) devices or sensitive financial data, but how can you get the job done without implementing an API gateway twice? At least?
Let’s explore how ngrok’s "API gateway" supports your mTLS-enabled service throughout the API lifecycle, from development to production.
Mutual TLS is a bidirectional security protocol that builds on the standard Transport Layer Security (TLS). Unlike TLS, where only the client has to authenticate the server before communicating with the server, mTLS requires both the client and the server to authenticate each other—a basic implementation of a zero-trust policy. When your API trusts no one by default, even those already in the network, and they must prove who they claim to be, you have strong guarantees your data only moves toward the right consumers.
Before we discuss how mTLS works with an API gateway, let’s take a 101-level look at TLS’s building blocks.
Private and public keys are crucial in cryptography, particularly in asymmetric encryption. A public key is a cryptographic key that you can use to encrypt messages or verify digital signatures. As the name suggests, you can share it widely with anyone.
A private key is one you keep secret. You can use a private key to generate digital signatures and decrypt messages signed with the associated public key, so exposing it negates the benefits of encryption entirely.
A certificate authority (CA) is a widely trusted entity that verifies the identities of various entities and issues digital certificates to facilitate encrypted communications over networks. On top of verification and issuance, CAs also maintain and manage the lifecycles of digital certificates, including renewing and revoking them.
A TLS certificate (X. 509) is a digital document that matches a public key to an entity's identity using a digital signature from a certificate authority. It captures key information, such as the algorithm used to create the certificate’s signature, the entity (usually a CA) that issued and signed the certificate, the certificate’s validity, and the entity identified by the certificate.
With standard TLS and an API gateway, the API consumer sends a request to the gateway and begins a TLS handshake, which returns its certificate to the client. The client contacts the CA to confirm the validity of the server’s certificate. Once that’s done, the client can use the embedded public key to decrypt the response via a secure communication channel.
That’s great, but it only protects the consumer—the API gateway, and your upstream API service, has no way of knowing who the consumer is or whether they should be allowed access to the data.
Mutual TLS starts the same way: The client starts a TLS handshake and verifies the server’s certificate against the CA. Here’s where it diverges—next, the server requests the client’s certificate and performs the same verification, ensuring both sides are identified and authenticated to exchange public keys to decrypt all the securely transmitted messages to come.
When paired with an API gateway, mTLS also:
Creates a baseline mechanism for authentication that’s more durable than basic username/password.
Identifies and authenticates clients that can’t log in using other means, such as machine-to-machine (M2M) processes or IoT devices.
Prevents malicious requests to your API aiming to extract data you need to keep secure.
Stops many potential attacks, like spoofing, brute force, and even phishing attacks by requiring API consumers to have a TLS certificate and private key in hand to complete the mTLS handshake.
Establishes non-repudiation in how API consumers interact with your service, in that they can’t deny their involvement in specific requests or actions, because of the certificate-based authentication.
To get started, you’ll need just two things:
An ngrok account.
ngrok installed where your API service(s) run—see our quickstarts for the agent CLI, Go SDK, Rust SDK, or Kubernetes Operator, although the instructions from here on out are for the CLI.
If you don't yet have a CA and certificates, you can create them using OpenSSL, starting with the CA private key (ca.key ).
openssl genpkey -algorithm RSA -out ca.key -pkeyopt rsa_keygen_bits:2048Next, generate an x509 self-signed certificate for the CA.
openssl req -x509 -new -nodes -key ca.key -sha256 -days 365 -out ca.crt -subj "/CN=ExampleCA"With the CA keys established, you can generate a certificate for your client.
First, generate a new key with OpenSSL, but with a different name: client.key.
openssl genpkey -algorithm RSA -out client.key -pkeyopt rsa_keygen_bits:2048Then generate the client's certificate signing request (CSR).
openssl req -new -key client.key -out client.csr -subj "/CN=ExampleClient"Sign the client’s request using the CA’s certificate and generate an x509 certificate.
openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt -days 365 -sha256You now configure features in ngrok like mTLS using our Traffic Policy engine, which lets you filter, take action on, and orchestrate traffic using the CEL configuration language.
The easiest way to use Traffic Policy on an API gateway and the ngrok agent is with a YAML file that specifies the phase on which you want to run specific actions.
Create a file called mtls.yaml on the system where you'll run the ngrok agent and paste in the following, also pasting in the contents of ca.crt in place of ... certificate ... .
on_tcp_connect:
- actions:
- type: terminate-tls
config:
mutual_tls_certificate_authorities:
- |
-----BEGIN CERTIFICATE-----
... certificate ...
-----END CERTIFICATE-----Start the ngrok agent to create an endpoint for your API service under an automatically-assigned static ngrok domain., referencing the Traffic Policy flie you just created.
ngrok http 80 --traffic-policy-file mtls.yamlRemember: you can always bring your own domain to ngrok!
To ensure you’ve correctly configured mTLS, send a request via curl to the endpoint without passing your client’s certificate. You’ll get back not a HTTP error response or an ngrok error code, but a TLS error triggered before your request even reaches your ngrok endpoint.
curl https://$YOUR-NGROK-DOMAIN
curl: (56) OpenSSL SSL_read: OpenSSL/3.0.13: error:0A00045C:SSL routines::tlsv13 alert certificate required, errno 0When you pass the client certificate in your request, you can access your API—proof you’ve successfully implemented mTLS with ngrok’s API gateway!
curl --cert client.crt --key client.key https://$YOUR-NGROK-DOMAINWe have a simple API service at ngrok-samples/api-demo on GitHub you can play around with to validate how enabling mTLS works on ngrok’s API gateway.
git clone git@github.com:ngrok-samples/api-demo.git
cd api-demo
node app.jsBy default, this API runs locally on port 5000.
Next, fire up your ngrok agent to create a new endpoint, which acts as your gateway between this API and the public internet—you can use the same certificates and Traffic Policy file you created just above.
ngrok http 4000 --traffic-policy-file mtls.yamlFinally, you can use curl to make a request entirely secured using mTLS.
curl --cert client.crt --key client.key https://$YOUR-NGROK-DOMAINDeploy your first API gateway with mTLS in just a few minutes—start by grabbing yourself a free ngrok account to help you meet security best practices, whether you’re working in a highly regulated industry or want peace of mind for your API project.
While deploying an API gateway with ngrok, you’re also saving yourself the hassle of configuring web servers, deploying service meshes on Kubernetes, or rolling out custom DNS. Are those on your critical path to going live with your API? ngrok removes all barriers to entry enabling mTLS on any API gateway project, getting you to production without complex reverse proxies or wrestling with your ops team for weeks.
Once you have mTLS enabled, you can extend your API gateway goodness with additional policies and a developer-first configuration workflow:
Have some strong thoughts about ngrok’s API gateway? We’d love to see them in our Community Repo—the home for all discussions, bug reports, and feedback about your mTLS and API gateway experience.