Configure mTLS on a workload
Upload a Trusted CA certificate and a CRL, turn on mTLS on a workload, and test the handshake, in Azion Console, with the Azion CLI, or with the API.
You can turn on mutual TLS (mTLS) on a workload in Azion Console, with the Azion CLI, or with the API. To serve HTTPS on your domain with a server certificate of your own instead, refer to Upload a digital certificate.
With mTLS on, the workload asks each client for a certificate during the TLS handshake. It checks that certificate against a Trusted CA certificate: the certificate of the certificate authority (CA) that signs your clients’ certificates. The setup takes three objects: the Trusted CA certificate, an optional certificate revocation list (CRL) from the same CA, and the mtls object of the workload.
An account that runs on API v3 has Domains in place of workloads, and sets mTLS on each domain. Turn on mTLS on a v3 domain carries those steps.
Prerequisites
Console
- mTLS activated on your account. Azion activates mTLS per account, so contact the Azion Sales team to turn it on.
- A workload whose deployment names an application, served over HTTPS. The client certificate travels in the TLS handshake, so mTLS checks HTTPS connections only. To create a workload, refer to Workloads quickstart.
- The certificate of your CA, in PEM format. A third-party CA issues it. A certificate that Azion generates cannot serve as the Trusted CA.
- (Optional) A CRL in PEM format, signed by the same CA.
- A client certificate that CA signed, with its private key, to test the workload.
- Access to Azion Console. For more information, refer to How to access Azion Console.
Upload the Trusted CA certificate
Certificate Manager stores the Trusted CA certificate with the type trusted_ca_certificate and no private key. The file must be in PEM format, with its -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines, and Certificate Manager refuses any other format. When your chain has intermediate certificates, include them in the same file.
Console
Azion Console uploads the Trusted CA certificate from the form that names it. The Trusted CA Certificate field closes with Create Digital Trusted CA certificate, which takes the PEM file without leaving the form. Turn on mTLS on the workload carries the steps, and Turn on mTLS on a v3 domain carries them for a domain.
The Trusted CA certificate reads inactive in Certificate Manager until a workload names it in its mtls object.
Upload a certificate revocation list
A CRL lists the certificates that a CA revoked before their expiration date, and the CA signs it. A workload with mTLS on names up to 100 CRLs in mtls.config.crl. This task is optional: skip it when your CA publishes no CRL.
Console
Azion Console uploads the CRL from the workload itself. The Certificate Revocation List (CRL) field closes with Create Digital CRL certificate, which takes the PEM file without leaving the form. Turn on mTLS on the workload carries the steps.
Certificate Manager stores the CRL and reads its last_update and next_update dates from the CRL itself.
Turn on mTLS on the workload
The mtls object of the workload turns the check on and names the Trusted CA certificate, the CRLs, and the verification mode. Pick the mode in verification:
enforce: the workload ends the handshake when a client presents no certificate, or a certificate the Trusted CA did not sign.permissive: every client completes the handshake, and a firewall rule decides which requests to refuse.
For what each mode does with each kind of client, refer to Verification modes.
Console
To turn on mTLS in Azion Console:
Go to Azion Console > Workloads.
Select the workload whose deployment names the application. Its edit form opens.
In the Protocol Settings section, turn on HTTPS support. Until then Mutual Authentication stays disabled, and the form says You can active this setting enabling HTTPS support above.
In the Mutual Authentication Settings section, turn on Mutual Authentication.
In Mode, select Enforce or Permissive. The form selects Enforce when the switch goes on.
In Trusted CA Certificate, select the certificate of your CA. The field is required, and Create Digital Trusted CA certificate, at the end of the list, uploads one without leaving the form.
Optionally, in Certificate Revocation List (CRL), select the CRLs the workload checks. Create Digital CRL certificate uploads one without leaving the form.
Select Save.
The Trusted CA certificate now reads active in Certificate Manager. The new mode takes several minutes to reach all of Azion’s distributed infrastructure. Until then, some requests still meet the previous configuration, so repeat a test before you trust its result.
The update fails when a certificate ID sits in the wrong field. A server certificate in mtls.config.certificate is refused with Invalid certificate type, MUST be a Trusted CA. A Trusted CA certificate in tls.certificate is refused with Invalid certificate type, MUST be an Edge Certificate. The CLI prints the message inside Error: Failed to update the Workload: [...]. For both fixes, refer to mTLS errors.
Turn on mTLS on a v3 domain
An account that runs on API v3 has Domains in place of workloads, and sets mTLS on each domain. To find out which model your account runs on, refer to Verify your account migration.
The rest of this page holds for a v3 domain as it is written, with one difference each: Upload the Trusted CA certificate is the same task, in the same Certificate Manager; Deny requests without a valid client certificate is the same rule, on the firewall the domain names in edge_firewall_id rather than the one in a workload’s deployment; Pass client certificate details to the origin is the same rule, on the application the domain names. A domain takes no certificate revocation list, so Upload a certificate revocation list does not apply.
To turn on mTLS on a domain in Azion Console:
Go to Azion Console > Domains, and select the domain.
In the Mutual Authentication Settings section, turn on Mutual Authentication.
In Mode, select Enforce or Permissive.
In Trusted CA Certificate, select the certificate of your CA. The field is required, and Create Digital Trusted CA certificate, at the end of the list, uploads one without leaving the form.
Select Save.
Test the handshake
Two requests to a domain of the workload show whether it checks clients: one without a client certificate, and one with a certificate the Trusted CA signed. Send them after the mTLS change propagates.
To send a request with no client certificate, run curl in verbose mode:
In enforce mode, the workload requests a certificate, the client sends none, and the handshake fails. curl exits with code 56. With curl built on LibreSSL, the verbose output ends like this:
To send a request with the client certificate, pass the certificate and its private key, here client.pem and client.key:
The handshake completes, and curl prints the status code your application returns:
The same results hold on the workload domain, <id>.map.azionedge.net. In permissive mode, both requests complete the handshake and reach the application, and so does a request with a certificate another CA signed.
Deny requests without a valid client certificate
In permissive mode, the workload refuses no client, so a rule in Rules Engine for Firewall must refuse the requests whose client certificate failed the check. The rule acts only when the firewall is in the workload’s deployment. To bind one, refer to Bind a firewall to a workload.
This rule denies the requests to <your-domain> whose client certificate did not pass validation:
To create the same rule in Azion Console:
Go to Azion Console > Firewall, and select the firewall in the workload’s deployment.
Select the Rules Engine tab, then Rule.
Enter a name that says which requests the rule refuses.
In Criteria, select the variable Host and the operator is equal, and enter your domain as the argument.
Select And, then the variable Client Certificate Validation and the operator is not equal. The argument is a list with one entry, Valid, which arrives selected.
In Behavior, select Deny (403 Forbidden).
Select Save.
For every variable, operator, and behavior a firewall rule takes, refer to Rules Engine for Firewall.
Once the rule propagates, a request to <your-domain> without a valid client certificate receives 403 Forbidden. A client whose certificate the Trusted CA signed still reaches the application.
Pass client certificate details to the origin
The Open Banking model requires the origin to receive the client certificate in request headers, from the variables ${ssl_client_escaped_cert} and ${ssl_client_s_dn_parsed}. ${ssl_client_escaped_cert} holds the client certificate as a URL-encoded PEM string, and ${ssl_client_s_dn_parsed} holds its subject Common Name (CN). A Request Phase rule in Rules Engine for Applications adds each header with the add_request_header behavior, on the application in the workload’s deployment.
This rule adds the client certificate to every request that carries one, in the Escaped-Client-Cert header:
The header argument takes the form Header-Name: value, and Azion Console refuses any other shape with Header must follow the header-name: value format. Add a second rule of the same shape for ${ssl_client_s_dn_parsed}, under a header name of your choice.
To create the same rule in Azion Console:
Go to Azion Console > Applications, and select the application in the workload’s deployment.
Select the Rules Engine tab, then + Rule.
Enter a name that says which header the rule adds.
In the Phase section, select Request Phase. The choice is final once the rule is created.
In Criteria, select the variable ${ssl_client_escaped_cert} and the operator exists.
In Behavior, select Add Request Header and enter Escaped-Client-Cert: ${ssl_client_escaped_cert} as the argument.
Select Save.
For every variable and behavior an application rule takes, refer to Rules Engine for Applications. The other client certificate variables are listed in mTLS variables.
Once the rules propagate, each request that Azion sends to the origin for a client with a certificate carries the headers.