How to configure mTLS

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 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, digital certificates, Trusted CA, and how mTLS works at Azion is available on the Support for mTLS page.

Add a Trusted CA to your Digital Certificates library

With your Trusted CA created, you need to add it to your library of Digital Certificates in the Edge Libraries section:

Access Azion Console > Digital Certificates.
Click the + Digital Certificate button.
Enter a name to identify this certificate.
In the Import or Request Certificate section, select the Import a Trusted CA certificate option.
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.

Click the Save button to proceed.

Access Real-Time Manager (RTM).
Open the Products menu, represented by three horizontal lines, and select Digital Certificates in the Edge Libraries section.
Click the Add certificate button and select the Trusted CA Certificate option from the dropdown menu.
On the new certificate registration page, set an identifying name for this certificate in the Digital Certificate Name field.
In Certificate, enter the content that represents your Trusted CA Certificate.

The certificate file must be of .pem format – Privacy Enhanced Mail (PEM). Example: certificate.pem.

Click the Save button to proceed.

You’ll be redirected to the Digital Certificates 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.

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

Still in the RTM, go to Products Menu > Domains.
Click on the domain you would like to configure mTLS for.
Enable the Enable Mutual Authentication (mTLS) switch.
Choose which verification mode you wish to use. It can be Enforce and Permissive.
Select the Trusted CA Certificate, added in the previous step, from the dropdown menu.
Click the Save button to proceed.

Adding specific rules for using Permissive mTLS

To configure the operation of Permissive mode:

Still in the Console, go to Products Menu > Edge Firewall.
Select the edge firewall you wish to use or click the + Edge Firewall button to create a new edge firewall.
Under Domains, select your application domain and click the > button to send the chosen domain to Selected.
Click the Save button.
Click the Rules Engine tab.
Click the + Rule button.
Choose an identifying name for this rule.
Define the Criteria and Behaviors specific to your need.

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

Make sure that the Status switch is activated.
Click the Save button.

Still in the RTM, go to Products Menu > Edge Firewall.
Select the edge firewall you wish to use or click the Add Rule Set button to create a new edge firewall.
Under Domains, select your application domain and click the > button to send the chosen domain to Chosen Domains.
Click the Save button.
Click the Rules Engine tab.
Click the New Rule button.
Choose an identifying name for this rule in the Rule set name field.
Define the Criteria and Behaviors specific to your need.

For this example, the logic will be:
- Criteria: If Hostname is equal yourDomain.com + And Client Certificate Validation is not equal true.
- Behaviors: Then Deny (403 Forbidden).

Make sure that the Active switch is activated.
Click the Save button.

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

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.

Go to the list of available variables

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

Within the Console, go to Products menu > Edge Application.
Find and click on the application with mTLS enabled.
Select the Rules Engine tab.
Click the + Rule button.
Set an identifier name for this rule.
Select Request Phase.
In the Criteria field, change the operator is equal to exists.
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). 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.

Make sure the Active switch is on.
Click the Save button.

Within the RTM, go to Products menu > Edge Application.
Find and click on the application with mTLS enabled.
Select the Rules Engine tab.
Click the New Rule button and select Request Phase.
Set an identifier name for this rule.
In the Criteria field, change the operator is equal to exists.
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). 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 + button.

Make sure the Active switch is on.
Click the Save button.

One way to test these header variables is with the curl 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.