Configure mTLS on a workload

You can turn on mutual TLS (mTLS) on a workload with the Azion CLI or 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 with Domains sets mTLS on each domain instead. For more information, refer to Domains.

Select an interface. The prerequisites and the steps of each task follow your choice.

Prerequisites

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

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.

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.

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.

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.

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:

In Azion Console, the same rule uses the variables Host and Client Certificate Validation, the operators is equal and is not equal, and the behavior Deny (403 Forbidden). To create the rule from Azion Console, the CLI, or the API, 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 rules from Azion Console, the CLI, or the API, 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.

Next steps