How to configure mTLS

Learn how to configure mTLS in your application at Azion.

View as Markdown

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.

If you’re not sure which steps apply to your account, see the Verify Your Account Migration guide 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 > 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.
  1. 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.

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:

  1. Access Azion Console > Workloads.
  2. Select your Workload .
  3. Still in the Console, go to Products Menu > Firewall.
  4. Click the Rules Engine tab.
  5. Click the + Rule button.
  6. Choose an identifying name for this rule.
  7. 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).
  1. Make sure that the Status switch is activated.
  2. Click the Save button.

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

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.

go to the list of available 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.
  1. Make sure the Active switch is on.
  2. 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.