Configure & Associate an mTLS Certificate
mTLS is a method that validates the digital certificate on the client side and on the edge.
Mutual Transport Layer Security (mTLS) is a security protocol that enables two-way authentication and encryption for network interaction. It confirms that both the client and the server are authenticated and have the clearance for effective communication.
To configure mTLS in your applications, you need a digital certificate with mTLS support signed by a third-party certificate authority (CA). At Azion, this type of certificate is called a Trusted CA.
There are separate instructions for API v3 using legacy Domains settings and API v4 using the new Workloads product.
Adding a Trusted CA certificate and associating it to a domain
- Access Azion Console > Certificate Manager.
- Click the + Digital Certificate button.
- Give your certificate an easy-to-remember name.
- Select the Import Trusted CA Certificate option.
- In the Private Certificate field, paste your Trusted CA, including the begin and end tags.
- Click the Save button.
After adding a Trusted CA to your certificate library, you need to configure which domains should operate with mTLS.
- Access Azion Console > Workloads.
- Click on the workload you’d like to configure mTLS for.
- Enable the Mutual Authentication switch.
- Choose which verification mode you wish to use.
- By selecting Enforce (default), mTLS is enabled in your application’s domain and all incoming traffic will comply with client and server authentication.
- By selecting Permissive, you must configure this mode in Firewall.
- Select the Trusted CA Certificate you created.
- Click the Save button.
- Access Azion Console > Certificate Manager.
- Click the + Digital Certificate button.
- Give your certificate an easy-to-remember name.
- Select the Import Trusted CA Certificate option.
- In the Private Certificate field, paste your Trusted CA, including the begin and end tags.
- Click the Save button.
After adding a Trusted CA to your certificate library, you need to configure which domains should operate with mTLS.
- Access Azion Console > Domains.
- Click on the domain you’d like to configure mTLS for.
- Enable the Mutual Authentication switch.
- Choose which verification mode you wish to use.
- By selecting Enforce (default), mTLS is enabled in your application’s domain and all incoming traffic will comply with client and server authentication.
- By selecting Permissive, you must configure this mode in Firewall.
- Select the Trusted CA Certificate you created.
- Click the Save button.
- Run the following
POSTrequest in your terminal, replacing[TOKEN VALUE]with your personal token and the certificate in thecertificateproperty:
| Key | Description |
|---|---|
name | Name of the certificate instance |
certificate | String that holds the certificate value. Must include the begin and end tags. Line feeds must be replaced by escape sequences (\n) |
certificate_type | Enum that indicates the type of the certificate. Trusted CA certificates are assigned the value trusted_ca_certificate |
- You’ll receive a response similar to this:
- Copy the
digital_certificate_idvalue. You’ll need it while associating it with a domain. - Run the following
POSTrequest in your terminal, replacing[TOKEN VALUE]with your personal token, the<application_id>with an application ID, and the<digital_certificate_id>with the ID of the Trusted CA you created:
| Key | Description |
|---|---|
name | Name of the domain instance |
cnames | Accepts an array of strings containing the CNAMEs for the domain as values |
digital_certificate_id | Enum that, when null, selects the Azion SAN certificate |
edge_application_id | The ID of the application linked to the domain |
is_mtls_enabled | Boolean that, when true, activates mTLS verification for the domain |
mtls_verification | Enum that sets the verification mode. Can be enforce or permissive |
mtls_trusted_ca_certificate_id | The ID of the Trusted CA |
- You’ll receive a response similar to this:
- Wait for the propagation time. Your domain should now be using the mTLS protocol.
- Run the following
POSTrequest in your terminal, replacing[TOKEN VALUE]with your personal token and the certificate in thecertificateproperty:
| Key | Description |
|---|---|
name | Name of the certificate instance |
certificate | String that holds the certificate value. Must include the begin and end tags. Line feeds must be replaced by escape sequences (\n) |
type | Enum that indicates the type of the certificate. Trusted CA certificates are assigned the value trusted_ca_certificate |
- You’ll receive a response similar to this:
- Copy the
digital_certificate_idvalue. You’ll need it while associating it with a Workload. - Run the following
POSTrequest in your terminal, replacing[TOKEN VALUE]with your personal token, the<application_id>with an application ID, and the<digital_certificate_id>with the ID of the Trusted CA you created:
| Key | Description |
|---|---|
name | Name of the domain instance |
cnames | Accepts an array of strings containing the CNAMEs for the domain as values |
digital_certificate_id | Enum that, when null, selects the Azion SAN certificate |
edge_application_id | The ID of the application linked to the domain |
is_mtls_enabled | Boolean that, when true, activates mTLS verification for the domain |
mtls_verification | Enum that sets the verification mode. Can be enforce or permissive |
mtls_trusted_ca_certificate_id | The ID of the Trusted CA |
- You’ll receive a response similar to this:
- Run the following
POSTrequest in your terminal to bind your new workload to an application, replacing[TOKEN VALUE]with your personal token, the<application_id>with an application ID, and the<workload_id>with the ID of the workload you created:
- Wait for the propagation time. Your domain should now be using the mTLS protocol.
Creating specific rules for Permissive mTLS
To configure a firewall to block access to a domain using the Permissive mode in mTLS, you must use the Rules Engine for Firewall. The following example describes a rule set that will block any incoming network traffic with the hostname mydomain.com whose client certificate validation isn’t true and deliver a 403 Forbidden error.
- Access Azion Console > Firewall.
- Configure an firewall for the mTLS domain.
- Click the Rules Engine tab.
- Click the + Rules Engine button.
- Give your rule an easy-to-remember name.
- In the Criteria section, as a variable, select Host.
- As a comparison operator, select is equal.
- As an argument, enter
mydomain.com. - Click the + And button to add a new criteria.
- As a variable, select Client Certificate Validation.
- As a comparison operator, select is not equal to.
- As an argument, enter
true. - In the Behavior section, select Deny (403 Forbidden).
- Click the Save button.
- Run the following
POSTrequest in your terminal, replacing[TOKEN VALUE]with your personal token and the<edge_firewall_id>with the ID of the firewall associated with the mTLS domain:
| Key | Description |
|---|---|
name | Name of the rule |
description | Description of the rule |
behaviors | Array that stores objects that define behaviors |
criteria | Array that stores objects that define criteria |
- You’ll receive a response similar to this:
Specifying mTLS variables in HTTP headers
If your application is part of the Open Banking model, you must specify the variables ${ssl_client_escaped_cert} and ${ssl_client_s_dn_parsed} in the HTTP headers of your application. You can use the Rules Engine for Application to create this behavior for your whole application.
Requires:
To test whether the headers you add are being sent in requests, you can run the following cURL command in your terminal from a directory containing the .pem files of your Trusted CA and its private key:
- Access Azion Console > Application.
- Find and click on the application with the mTLS domain.
- Click the Rules Engine tab.
- Click the + Rule button.
- Give your rule an easy-to-remember name.
- Select Request Phase.
- In the Criteria field, enter the desired mTLS variable. Example:
${ssl_client_escaped_cert}. - Select the comparison operator exists.
- In the Behaviors section, select the Add Response Header behavior.
- As an argument, enter
Mtls-Variable-Name: ${ssl_variable_name}, replacing the name and variable with the mTLS variable you wish to insert in your application’s header.- Example:
Escaped-Client-Cert: ${ssl_client_escaped_cert}
- Example:
- To add another variable, click the + And button in the Criteria section and repeat the remaining steps.
- Click the Save button when you’re done.
- Run the following
POSTrequest in your terminal, replacing[TOKEN VALUE]with your personal token and the<application_id>with the ID of the application associated with the mTLS domain:
- You’ll receive a response similar to this:
- Repeat the previous step for each mTLS variable required in the headers.