Mutual TLS Authentication (mTLS) is a network security protocol that ensures both the client and server authenticate each other using digital certificates, providing encrypted and trusted communication between both parties. This is in contrast to standard TLS, where only the server is authenticated by the client. By verifying the clients, the server owner is able to restrict access only to verified clients, strengthening security. This guide walks you through enabling mTLS on your ngrok hosted endpoints using the terminate-tls Traffic Policy action.

​
What you’ll need

  • Ensure you have openssl installed.

​
1. Provision your certificates and credentials

Although ngrok can automatically provision your certificates when you use standard TLS, you’ll have to provide your own certificate authority (CA) for mTLS. The CA is responsible for issuing, digitally signing, and verifying the authenticity of client certificates. Keep in mind:
  1. ngrok uses the CA certificate to verify the client certificate.
  2. Once the CA signs a client certificate, the client certificate is used to grant the client access your endpoints.
  3. ngrok does not generate CA and client certificates for you when you use mTLS; you must generate them yourself.
  4. Though your CA certificate must be uploaded and hosted on the ngrok SaaS platform, your client certificates need to be distributed to any client or device that needs access to your endpoints.

​
Generate your own certificates

Most organizations have their own certificate management infrastructure, so this step is optional if you already have a CA and client certificates to work with.
To begin, create a new CA that will be used to sign the client certificate, as shown below. With this approach you can generate multiple client certificates that are trusted by the CA if needed. 
# 1. Generate CA private key (ca.key)
openssl genpkey -algorithm RSA -out ca.key -pkeyopt rsa_keygen_bits:2048

# 2. Generate CA certificate (ca.crt)
openssl req -x509 -new -nodes -key ca.key -sha256 -days 365 -out ca.crt -subj "/CN=ExampleCA"

# 3. Generate client private key (client.key)
openssl genpkey -algorithm RSA -out client.key -pkeyopt rsa_keygen_bits:2048

# 4. Generate client certificate signing request (CSR) (client.csr)
openssl req -new -key client.key -out client.csr -subj "/CN=ExampleClient"

# 5. Generate client certificate (client.crt)
openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt -days 365 -sha256
These commands result in five new files: ca.key, ca.crt, client.key, client.csr, and client.key. You will use the contents of ca.crt in your traffic policy to validate requests via curl, which, in turn, uses client.key and client.crt.

​
2. Create a traffic policy

Using the CA certificate generated in the previous step, you can specify the mutual_tls_certificate_authorities field in a traffic policy to trust the CA that issued the client certificate. 
on_tcp_connect:
  -     actions:
      -         type: terminate-tls
        config:
          mutual_tls_certificate_authorities:
            - -----BEGIN CERTIFICATE-----
... certificate ...
-----END CERTIFICATE-----
You may also optionally upload the CA certificate in the ngrok dashboard and use its ID in the mutual_tls_certificate_authorities array.

​
3. Start an endpoint with the traffic policy

ngrok http 8080 --url $YOUR_DOMAIN --traffic-policy-file /path/to/policy.yml

​
4. Test your endpoint

Test out that everything works by making a request to your endpoint using the --cert and --key flags to specify the client certificate and private key. 
curl --cert client.crt --key client.key https://$YOUR_DOMAIN