How to configure and associate an mTLS certificate to a domain
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.
Adding a Trusted CA certificate and associating it to a domain
- Access Azion Console > Digital Certificates.
- 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 edge application’s domain and all incoming traffic will comply with client and server authentication.
- By selecting Permissive, you must configure this mode in Edge 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:
curl --location 'https://api.azionapi.net/digital_certificates' --header 'Accept: application/json; version=3' --header 'Authorization: Token [TOKEN VALUE]' --header 'Content-Type: application/json' --data '{ "name": "Trusted CA - mydomain.com", "certificate": "-----BEGIN CERTIFICATE-----MIIDCTCCAfGgAwIBAgIJAPpKHOLMIGuAMA0GCSqGSIb3DQEBBQUAMBsxGTAXBgNVBAMMEHd3dy5teWRvbWFpbi5jb20wHhcNMTgwMzI3MjAwOTA0WhcNMjgwMzI0MjAwOTA0WjAbMRkwFwYDVQQDDBB3d3cubXlkb21haW4uY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAt25cziDBsHbZzZhy9BPLApPf9OmE67k9pr7VezsRkIw4trY2xtJXFB7itT1p7HxbLBoL5u8FGmMKssB+XTmztmgty43ogor1KSjUgfZgrpAqyXtrbSM5g+14c0VO9S0LkkePlHvul0UiblJj7K+gkvc6sZqXZY+TI1BPqeuOs9A4LLCUGziyNv0qJfIL5RZm07Yy35BEBTTxUWVL2msfaUH2uPM5XN5eFC7oKN0/3NuYIboRmyk+P7CDC99M8Mp/wOjiB+yVGZVTjeqGPI8nFWJl2wtyuiZ4VvW84xQPjwtid1v1KENK/ixMAAXi2cQ9gNRX+/USoneuWj5n4QUj6QIDAQABo1AwTjAdBgNVHQ4EFgQU2sDgtyYMDXvw79OhdvAFqcLmcwkwHwYDVR0jBBgwFoAU2sDgtyYMDXvw79OhdvAFqcLmcwkwDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQUFAAOCAQEAKzCMiG67IPwJK6MIJ31N734AofjkOf+fffxNtfYmH0XGORHPYUxCxsLxXiSFgPvubWh+7vLsKAm67bflMWbn982aiOR0O/LJhLvhj6F+wgv0aDYup181Hm8Ob/88ldbF6ND1TqzVATS0WDfl+z1QBKtNdDm3Nv45IZ83ob7OhIzD9MwL6tflBPDpWOYtmBDn0xSP6ra9d8oa6jK1fe2/5A7LY41acjbbNrLbFDYP7hcx02TmCfSMut+ysaZ/blay4SbbwNlt92KhJw07UEKgXXbgyXGoFQkU8V+r2AZcgt0XM9jvwTc01Sbq/gegd2GMAj3xrTwkn5UNzFs56FCgNg==-----END CERTIFICATE-----", "certificate_type": "trusted_ca_certificate"}'| 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:
{ "results": { "id": <digital_certificate_id>, "name": "Trusted CA - mydomain.com", "issuer": "CA name", "subject_name": [], "validity": "2028-03-24 20:09:00-03:00", "status": "Active", "certificate_type": "trusted_ca_certificate", "managed": false }}- 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<edge_application_id>with an edge application ID, and the<digital_certificate_id>with the ID of the Trusted CA you created:
curl --location 'https://api.azionapi.net/domains' \--header 'Accept: application/json; version=3' \--header 'Authorization: Token [TOKEN VALUE]' \--header 'Content-Type: application/json' \--data '{ "name": "mydomain.com", "cnames": [ "mydomain.com" ], "digital_certificate_id": null, "edge_application_id": <edge_application_id>, "is_mtls_enabled": true, "mtls_verification": "enforce", "mtls_trusted_ca_certificate_id": <digital_certificate_id>}'| 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:
{ "id": <domain_id>, "name": "mydomain.com", "cnames": [ "mydomain.com" ], "cname_access_only": true, "digital_certificate_id": null, "edge_application_id": <edge_application_id>, "is_active": true, "domain_name": "abcde12345.map.azionedge.net", "environment": "production", "is_mtls_enabled": true, "mtls_verification": "enforce", "mtls_trusted_ca_certificate_id": <digital_certificate_id>, "edge_firewall_id": null}- 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 Edge 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 > Edge Firewall.
- Configure an edge 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:
curl --location 'https://api.azionapi.net/edge_firewall/<edge_firewall_id>/rules_engine' --header 'Accept: application/json; version=3' --header 'Authorization: Token [TOKEN VALUE]' --header 'Content-Type: application/json' --data '{ "name": "403 Host=mydomain.com and CCV!=true", "description": "Delivers a 403 if the hostname does not match mydomain.com and if the certificate validation fails.", "behaviors": [ { "name": "deny" } ], "criteria": [ [ { "variable": "host", "operator": "is_equal", "conditional": "if", "argument": "mydomain.com" }, { "variable": "client_certificate_validation", "operator": "is_not_equal", "conditional": "and", "argument": "true" } ] ]}'| 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:
{ "results": { "name": "403 Host=mydomain.com and CCV!=true", "description": "Delivers a 403 if the hostname does not match mydomain.com and if the certificate validation fails.", "behaviors": [ { "name": "deny" } ], "criteria": [ [ { "variable": "host", "operator": "is_equal", "conditional": "if", "argument": "mydomain.com" }, { "variable": "client_certificate_validation", "operator": "is_not_equal", "conditional": "and", "argument": "true" } ] ], "id": <rule_set_id>, "order": 0 }}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 Edge 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:
curl -skv https://mydomain.com/ -H "Pragma: azion-debug-cache" -o /dev/stdout --cert cert.pem --key key.pem- Access Azion Console > Edge 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<edge_application_id>with the ID of the application associated with the mTLS domain:
curl --location 'https://api.azionapi.net/edge_applications/<edge_application_id>/rules_engine/request/rules' --header 'Accept: application/json; version=3' --header 'Content-Type: application/json' --header 'Authorization: Token [TOKEN VALUE]' --data '{ "name": "mTLS variables", "description": "Adds certificate values according to Open Banking standards", "phase": "request", "behaviors": [ { "name": "add_request_header", "target": "Escaped-Client-Cert: ${ssl_client_escaped_cert}" } ], "criteria": [ [ { "variable": "${ssl_client_escaped_cert}", "operator": "exists", "conditional": "if", "input_value": "" } ] ]}'- You’ll receive a response similar to this:
{ "results": { "id": <rule_id>, "name": "mTLS variables", "phase": "request", "behaviors": [ { "name": "add_request_header", "target": "Escaped-Client-Cert: ${ssl_client_escaped_cert}" } ], "criteria": [ [ { "variable": "${ssl_client_escaped_cert}", "operator": "exists", "conditional": "if", "input_value": "" } ] ], "description": "Adds certificate values according to Open Banking standards" }}- Repeat the previous step for each mTLS variable required in the headers.