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

There are separate instructions using legacy Domains settings using the new Workloads product.

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

Adding specific rules for using Permissive mTLS

To configure the operation of Permissive mode:

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.

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