mTLS

Mutual TLS (mTLS), also called mutual authentication, adds a client check to the TLS handshake: the client presents a certificate too, and the server validates it. On a workload, Azion validates the client certificate against a Trusted CA certificate, one of the types listed in Certificates. mTLS is optional on a workload, and the Open Banking model requires it, so workloads that serve financial services and payments often need it. For the mtls row among every other workload field, refer to Workload settings.

Fields

The mtls object of a workload turns the client certificate check on and names what the workload checks against. Set it with PATCH /v4/workspace/workloads/{workload_id}, or in the JSON file of azion update workload --file, which reads the workload ID from an "id" key in the file.

The Trusted CA certificate is the certificate of the authority that signs your clients’ certificates. You upload it with no private key, and the API refuses the ID of a server certificate in mtls.config.certificate. A Trusted CA certificate reads inactive in Certificate Manager until a workload names it, and active from then on.

A CRL lists certificates that their issuer revoked before they expired. A CRL is attached to a workload only through mtls.config.crl, on a workload with mtls.enabled set to true, and one workload can name several CRLs in the same array.

For example, a workload that admits only clients your certificate authority signed, and attaches one CRL, sends this file, saved as mtls.json:

Apply it with the CLI:

The command prints the ID of the workload it changed:

The workload then reads back with this mtls object:

On API v3, mTLS belonged to the domain object, in is_mtls_enabled, mtls_verification, and mtls_trusted_ca_certificate_id. On API v4 the same settings are mtls.enabled, mtls.config.verification, and mtls.config.certificate on the workload. For the full mapping between the two models, refer to API v4 Migration.

Verification modes

The mtls.config.verification field decides what a workload does with a client that presents no certificate, or a certificate the Trusted CA did not sign. In enforce mode, the workload requests the client certificate during the TLS handshake and ends the handshake when the check fails. The table shows what each client receives from a workload in each mode:

enforce blocks every client whose identity the workload cannot verify, on your own domains and on the workload domain alike. Use it when every legitimate client holds a certificate your certificate authority signed.

permissive lets every client complete the handshake and leaves the decision to your rules. Use it to test mTLS, or to admit clients under specific conditions. To refuse the rest, add a firewall rule on the Client Certificate Validation variable, as the section Client certificate data in rules describes.

A change to mtls takes several minutes to reach all of Azion’s distributed infrastructure, and propagation is best-effort. Until it completes, some requests meet the old mode and others the new one. Before you rely on a change, send a request with no client certificate and confirm that the result matches the new mode.

Client certificate data in rules

Rules Engine reads details of the client certificate, so a rule can act on the identity of the client.

In Rules Engine for Firewall, the Client Certificate Validation variable evaluates whether the certificate in the request is valid against the workload’s Trusted CA. On a workload in permissive mode, a rule that denies requests where Client Certificate Validation is not equal to true returns 403 Forbidden to every client without a valid certificate. The Client Certificate Validation criterion appears only on an account where mTLS is activated.

A firewall rule can also match attributes of the client certificate, such as the Common Name (CN), the issuer, or the fingerprint, which the mTLS header variables carry. Those variables must be set in your application before a firewall rule can use them as criteria.

An application sets the mTLS header variables as request headers, for example to meet Open Banking requirements. The list of variables Rules Engine accepts is on Rules Engine for Applications. For the rule configuration step by step, refer to Configure mTLS on a workload.

Requirements

A workload checks client certificates only when these conditions hold:

• mTLS is activated on your account. Azion activates mTLS per account. To activate it, contact the Sales team.
• The workload serves HTTPS. The client certificate travels in the TLS handshake, so mTLS works only on HTTPS connections. mTLS settings on a workload that serves HTTP only check nothing.
• A Trusted CA certificate exists in Certificate Manager. A third-party certificate authority issues it, and you upload it before you set mtls.config.certificate. A certificate that Azion generates, such as the Azion SAN certificate, cannot serve as the Trusted CA.
• Clients send SNI in enforce mode. Server Name Indication (SNI) is the TLS extension that names the host in the handshake. A connection without SNI reaches the default configuration, which presents the Azion SAN certificate. On a workload in enforce mode, Azion closes such a connection before it resolves a route of your application.

For the number of certificates an account can hold and the maximum size of a Trusted CA certificate, refer to Workloads limits.

Errors

The API refuses the first two requests below with the message in the first column. The CLI prints the message inside Error: Failed to update the Workload: [...], followed by Check your settings and try again. If the error persists, contact Azion support. The last row is what a client sees, not an API message.

The handshake failure shows in verbose curl output. Send a request with no client certificate to a workload in enforce mode:

The workload requests a certificate, the client sends none, and the connection ends:

Related resources