> ## Documentation Index
> Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# mTLS Termination

> Learn how to enable Mutual TLS (mTLS) termination with your ngrok agents.

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.

<img src="https://mintcdn.com/ngrok/v8P7gS4URgFQZWGA/agent/img/agent-mutual-tls-handshake-diagram.png?fit=max&auto=format&n=v8P7gS4URgFQZWGA&q=85&s=fcdeb3d9674324c96531208ddd66a99e" alt="Diagram showing the 7-step mutual TLS handshake between a client and the ngrok agent, including certificate exchange and verification" width="1749" height="341" data-path="agent/img/agent-mutual-tls-handshake-diagram.png" />

This guide walks you through enabling mTLS on your ngrok hosted endpoints using [the `terminate-tls` Traffic Policy action](/traffic-policy/actions/terminate-tls/).

## What you'll need

* Ensure you have [openssl](https://docs.openiam.com/docs-4.2.1.3/appendix/2-openssl) installed.

## 1. Provision your certificates and credentials

Although ngrok can [automatically provision your certificates](/gateway/tls-certificates) when you use standard TLS, you'll have to provide your own TLS 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.
</Note>

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.

```bash theme={null}
# 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.

<CodeGroup>
  ```yaml policy.yml theme={null}
  on_tcp_connect:
    - actions:
        - type: terminate-tls
          config:
            mutual_tls_certificate_authorities:
              - |-
                -----BEGIN CERTIFICATE-----
                ... certificate ...
                -----END CERTIFICATE-----
  ```

  ```json policy.json theme={null}
  {
    "on_tcp_connect": [
      {
        "actions": [
          {
            "type": "terminate-tls",
            "config": {
              "mutual_tls_certificate_authorities": [
                "-----BEGIN CERTIFICATE-----\n... certificate ...\n-----END CERTIFICATE-----"
              ]
            }
          }
        ]
      }
    ]
  }
  ```
</CodeGroup>

You may also optionally [upload the CA certificate](https://dashboard.ngrok.com/tls-cert-authorities) in the ngrok dashboard and use its ID in the `mutual_tls_certificate_authorities` array.

## 3. Start an endpoint with the Traffic Policy

```bash theme={null}
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.

```bash theme={null}
curl --cert client.crt --key client.key https://$YOUR_DOMAIN
```