# How to configure mTLS

import DocButton from '~/components/webkit/DocButton.vue';
import Tabs from '~/components/tabs/Tabs'
import Apiv4Rollout from '~/includes/snippets/apiv4Rollout/en/snippet.mdx'

<Apiv4Rollout />

**Mutual Transport Layer Security (mTLS)** is an encryption protocol based on *Transport Layer Security (TLS)*, which validates the digital certificate on both ends of a request.

To configure mTLS in your applications, you need to activate the service through [Azion Sales Team](https://www.azion.com/en/contact/) in addition to having a digital certificate with mTLS support, provided by a third-party certificate authority. At Azion, this certificate is called **Trusted Certificate (Trusted CA)**.

More information about requirements, certificate manager, Trusted CA, and how mTLS works at Azion is available on the [Support for mTLS page](/en/documentation/products/secure/firewall/mtls/).

There are separate instructions using [legacy Domains](/en/documentation/products/build/applications/domains/) settings using the new [Workloads](/en/documentation/products/secure/workloads) product.

:::tip
If you're not sure which steps apply to your account, see [the Verify Your Account Migration guide](/en/documentation/products/guides/verify-account-migration/) to determine if your account has already been migrated.
:::

---

## Add a Trusted CA to your Certificate Manager library

With your **Trusted CA** created, you need to add it to your library of **Certificate Manager** in the **Edge Libraries** section:

1. Access [Azion Console](/en/documentation/products/guides/how-to-access-azion-console/) > **Certificate Manager**.
2. Click the **+ Certificate Manager** button.
3. Enter a name to identify this certificate.
4. In the **Import or Request Certificate** section, select the **Import a Trusted CA certificate** option.
5. Enter the content that represents your certificate in the **Private Certificate** field.
- The certificate file must be of `.pem` format – Privacy Enhanced Mail (PEM). Example: `certificate.pem`.
6. Click the **Save** button to proceed.

You'll be redirected to the **Certificate Manager** page, where all your certificates are listed, including this newly added one.

---

## Choose the domains

After adding a **Trusted CA** to your certificate library, you need to configure which domains should operate with mTLS.

1. Still in the Console, go to **Products Menu** > **Domains**.
2. Click on the domain you would like to configure **mTLS** for.
3. Enable the **Mutual Authentication Settings** switch.
4. Choose which verification mode you wish to use. It can be `Enforce` and `Permissive`.
5. Select the **Trusted CA Certificate**, added in the previous step, from the *dropdown* menu.
6. Click the **Save** button to proceed.

:::note
By selecting `Enforce` verification (default), mTLS is enabled in your application and all incoming traffic will comply with client and server authentication. 
However, if you're looking to test or access your application from specific conditions, choose the `Permissive` mode. The `Permissive` mode is set up through the **Rules Engine** of the **Firewall** and the steps are described in the section below.

It's important to remember that misconfiguring the `Permissive` verification mode can result in security incidents.
:::

---

## Adding specific rules for using Permissive mTLS

To configure the operation of `Permissive` mode: 

<Tabs client:visible>
    <Fragment slot="tab.consoleworkloads">Console - Workloads</Fragment>
    <Fragment slot="tab.consoledomains">Console - Domains</Fragment>

<Fragment slot="panel.consoleworkloads">

1. Access [Azion Console](/en/documentation/products/guides/how-to-access-azion-console/) > **Workloads**.
2. Select your Workload .
5. Still in the Console, go to **Products Menu** > **Firewall**.
6. Click the **Rules Engine** tab.
7. Click the **+ Rule** button.
8. Choose an identifying name for this rule.
9. Define the **Criteria** and **Behaviors** specific to your needs.
- For this example, the logic will be:
    - Criteria: *If* `Host` *is equal* `yourDomain.com` *+ And* `Client Certificate Validation` *is not equal* `true`.
    - Behaviors: *Then* `Deny (403 Forbidden)`.
10.  Make sure that the **Status** switch is activated.
11. Click the *Save* button.

</Fragment>

<Fragment slot="panel.consoledomains">

1. Access [Azion Console](/en/documentation/products/guides/how-to-access-azion-console/) > **Domains**.
2. Select your Domain.
3. Under **Settings** select the firewall you wish to use or click the **+ Firewall** button to create a new firewall.
4. Click the **Save** button.
5. Still in the Console, go to **Products Menu** > **Firewall**.
6. Click the **Rules Engine** tab.
7. Click the **+ Rule** button.
8. Choose an identifying name for this rule.
9. Define the **Criteria** and **Behaviors** specific to your needs.
- For this example, the logic will be:
    - Criteria: *If* `Host` *is equal* `yourDomain.com` *+ And* `Client Certificate Validation` *is not equal* `true`.
    - Behaviors: *Then* `Deny (403 Forbidden)`.
11.  Make sure that the **Status** switch is activated.
12. Click the *Save* button.

</Fragment>
</Tabs>

Without mTLS support enabled in your Azion account, the Criteria **Client Certificate Validation** option won't appear.

:::note
In this example, the Rule Set will block `(Error 403 Forbidden)` any incoming network traffic with a *hostname* equal to `yourDomain.com` whose client certificate validation isn't true.
:::

---

## Specifying mTLS variables in the application header

If your application is part of the Open Banking model, you' wi'll need to specify the variables `${ssl_client_escaped_cert}` and `${ssl_client_s_dn_parsed}` in the *header* of your application. You can also insert other mTLS variables.

<DocButton href="/en/documentation/products/build/applications/rules-engine/" label="go to the list of available variables" kind="secondary" size="medium" />

To add a variable to your application header, follow the steps:

1. Within the **Console**, go to **Products menu** > **Applications**.
2. Find and click on the application with mTLS enabled.
3. Select the **Rules Engine** tab.
4. Click the **+ Rule** button.
5. Set an identifier name for this rule.
6. Select **Request Phase**.
7. In the **Criteria** field, change the operator `is equal` to `exists`.
8. In the **Behaviors** field, select the *Add Request Header* option and add the variable you wish to insert in your application's header.
- The use of the prefix `X-` in the `header-name` of custom HTTP variables is discouraged by the HTTP development organization, Internet Engineering Task Force (IETF), since 2012 ([RFC 6648](https://datatracker.ietf.org/doc/rfc6648/)). The IETF recommends using a simple `header-name`, which indicates the actual use of the variable, but which does not conflict with standard variables.
- To add another variable, click the `+ Add Behavior` button.
9. Make sure the **Active** switch is on.
10.  Click the **Save** button.

One way to test these header variables is with the [curl](https://curl.se/) tool. From a directory containing your **Trusted CA** and its key in a `.pem` file (For example: `cert.pem` and `key.pem`), open the terminal and run `curl -skv https://<yourDomain.com>/ -H "pragma:azion-debug-cache" -o /dev/stdout --cert cert.pem --key key.pem`. You should find `header-name:value` from the added variables on the terminal response.