Skip to main content

Using Mutual TLS (mTLS) Authentication

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​

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​

note

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.

Loading…

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.

1. 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.

Loading…

You may also optionally upload the CA certificate in the ngrok dashboard and use its ID in the mutual_tls_certificate_authorities array.

2. Start an endpoint with the traffic policy​

Loading…

3. 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.

Loading…

Setting up mTLS with Edges​

Edges are deprecated. We do not recommend setting up mTLS with Edges.