1 of 20
2 of 20
3 of 20
4 of 20
5 of 20
6 of 20
7 of 20
8 of 20
9 of 20
10 of 20
11 of 20
12 of 20
13 of 20
14 of 20
15 of 20
16 of 20
17 of 20
18 of 20
19 of 20
20 of 20

doc

How to configure mTLS on your Edge Application Domains

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 our Sales Channel in addition to having a digital certificate with mTLS support, provided by a third-party certificate authority. At Azion, we call this certificate 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.

  1. Adding a Trusted CA to your Digital Certificates library
  2. Choose the domains
  3. Add specific rules for using Permissive mTLS
  4. Specifying mTLS variables in the application header
  5. Related content

1. 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, under Edge Libraries:

  1. Go to the Real-Time Manager (RTM) and click on the Products Menu, indicated by the ☰ icon. Search for the Edge Libraries category and click on Digital Certificates.
  2. Click the Add certificate button and select the Trusted CA Certificate option from the dropdown menu.
  3. On the new certificate registration page, set an identifying name for this certificate in the “Digital Certificate Name” field.
  4. Enter in Certificate the content that represents your Trusted CA.

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

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

2. Choose the domains

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

  1. Go to the Domains page, found in the Products Menu (☰).
  2. Click on the domain you would like to configure mTLS for.
  3. Enable the Enable Mutual Authentication (mTLS) 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 Edge 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 Edge Firewall and the steps are described in the section below.

It is important to remember that misconfiguring the Permissive verification mode can result in security incidents.

3. Adding specific rules for using Permissive mTLS

To configure the operation of Permissive mode:

  1. Go to the Products Menu (☰).
  2. In the SECURE category, click Edge Firewall.
  3. If there’s no Firewall configured, click Add Rule Set and set an identification name for the new rules.
  4. Under Domain Settings, select your application domain and click the > button to send the chosen domain to Chosen Domains.
  5. Click Save.
  6. With the Rule Set created, click the Rules Engine tab of the Edge Firewall.
  7. Click the New Rule button.
  8. Choose an identifying name for this rule in Rule Name.
  9. Define the Criteria and Behaviors specific to your need.

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

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

Without mTLS support enabled in your Azion account, the Criteria option Client Certificate Validation will not appear.

In this example logic, the Rule Set created will block (Error 403 Forbidden) any incoming network traffic with a hostname equal to {yourDomain.com} whose client certificate validation is not true.

4. Specifying mTLS variables in the application header

If your application is part of the Open Banking model, you will 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. Check the list of available variables and their descriptions.

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

  1. Within the RTM, open the Products Menu (☰).
  2. Click on Edge Application.
  3. Find and click on the application with mTLS enabled.
  4. Within the settings of your Edge Application, click the Rules Engine tab.
  5. Click the New Rule button and select Request Phase.
  6. Set an identifier name for this Rule.
  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.

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

  9. Make sure the Active switch is on.
  10. To add another variable, click the + button and return to step 7.
  11. 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.

Didn’t find what you were looking for? Open a ticket.