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

Run the following POST request in your terminal, replacing [TOKEN VALUE] with your personal token and the certificate in the certificate property:

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-----\nMIIDCTCCAfGgAwIBAgIJAPpKHOLMIGuAMA0GCSqGSIb3DQEBBQUAMBsxGTAXBgNV\nBAMMEHd3dy5teWRvbWFpbi5jb20wHhcNMTgwMzI3MjAwOTA0WhcNMjgwMzI0MjAw\nOTA0WjAbMRkwFwYDVQQDDBB3d3cubXlkb21haW4uY29tMIIBIjANBgkqhkiG9w0B\nAQEFAAOCAQ8AMIIBCgKCAQEAt25cziDBsHbZzZhy9BPLApPf9OmE67k9pr7VezsR\nkIw4trY2xtJXFB7itT1p7HxbLBoL5u8FGmMKssB+XTmztmgty43ogor1KSjUgfZg\nrpAqyXtrbSM5g+14c0VO9S0LkkePlHvul0UiblJj7K+gkvc6sZqXZY+TI1BPqeuO\ns9A4LLCUGziyNv0qJfIL5RZm07Yy35BEBTTxUWVL2msfaUH2uPM5XN5eFC7oKN0/\n3NuYIboRmyk+P7CDC99M8Mp/wOjiB+yVGZVTjeqGPI8nFWJl2wtyuiZ4VvW84xQP\njwtid1v1KENK/ixMAAXi2cQ9gNRX+/USoneuWj5n4QUj6QIDAQABo1AwTjAdBgNV\nHQ4EFgQU2sDgtyYMDXvw79OhdvAFqcLmcwkwHwYDVR0jBBgwFoAU2sDgtyYMDXvw\n79OhdvAFqcLmcwkwDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQUFAAOCAQEAKzCM\niG67IPwJK6MIJ31N734AofjkOf+fffxNtfYmH0XGORHPYUxCxsLxXiSFgPvubWh+\n7vLsKAm67bflMWbn982aiOR0O/LJhLvhj6F+wgv0aDYup181Hm8Ob/88ldbF6ND1\nTqzVATS0WDfl+z1QBKtNdDm3Nv45IZ83ob7OhIzD9MwL6tflBPDpWOYtmBDn0xSP\n6ra9d8oa6jK1fe2/5A7LY41acjbbNrLbFDYP7hcx02TmCfSMut+ysaZ/blay4Sbb\nwNlt92KhJw07UEKgXXbgyXGoFQkU8V+r2AZcgt0XM9jvwTc01Sbq/gegd2GMAj3x\nrTwkn5UNzFs56FCgNg==\n-----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_id value. You’ll need it while associating it with a domain.
Run the following POST request 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.

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.

Access Real-Time Manager (RTM) > Digital Certificates.
Click the Add certificate button.
Select the Trusted CA Certificate option from the dropdown.
Give your certificate an easy-to-remember name.
In the 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 Real-Time Manager (RTM) > Domains.
Click on the domain you’d like to configure mTLS for.
Enable the Enable Mutual Authentication (mTLS) 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.

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.

Access Real-Time Manager (RTM) > Edge Firewall.
Configure an edge firewall for the mTLS domain.
Click the Rules Engine tab of the Edge Firewall.
Click the New Rule button.
Give your rule an easy-to-remember name.
In the Criteria section, as a variable, select Hostname.
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 POST request 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

Run the following POST request 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.

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}

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.

Access Real-Time Manager (RTM) > Edge Application.
Find and click on the application with the mTLS domain.
Click the Rules Engine tab.
Click the New Rule button and select Request Phase.
Give your rule an easy-to-remember name.
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}

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.