📘

Limited Availability

This feature is only available to select customers. Talk to your account team about eligibility.

The transport layer security (TLS) protocol is used to secure connections between a client and server. With a common TLS-secured web connection, only the client validates the identity of the server before allowing communications. With mutual TLS-secured web connections, both the client and the server validate the identity of one another, before allowing communication between the two. The client and server each present a TLS identity certificate to the other, with each side verifying the authenticity, during what's called the "TLS handshake”. Once verified, the identity information is used to authorize additional communication requests between the two.

Why you need it

The Enforce mTLS settings are part of the authorization logic for your delivery configuration ("property"). They're a way to ensure requests processed by your property are coming from TLS connections set in an mTLS configuration you've applied.

The server's certificate, what we refer to as an ​Akamai​ edge certificate, and its settings aren't automatically bound to a specific property. You can set it up to support requests from multiple edge certificates, each with varying TLS settings to support different use cases:

• An edge certificate with a specific hostname with mTLS.

• An edge certificate that uses a wildcard hostname without mTLS.

For example, this behavior's settings can be applied to enforce mTLS for requests to the specific hostname associated with the edge certificate with mTLS. But, they wouldn't apply to requests for the wildcard hostname.

How it works

A client makes a connection to a particular edge certificate on the ​Akamai​ network. The client then makes a request for your property. The request is processed by your property and Enforce mTLS settings are applied. Configure them to ensure these requests came from a TLS connection, where the expected mTLS configuration settings were applied. After this validation takes place, further request processing can continue. If there's a mismatch, you can apply custom error handling.

Implementation

These sections offer some basic workflows you can follow to add this support.

Before you begin

There are a few prerequisites you need to meet before adding mTLS support to your property:

• Create your CA set for the client. You need to set up a certificate authority (CA) set with ​Akamai​'s Mutual TLS Edge TrustStore application. Here, you'll add your own secure certificates that requesting clients will exchange with the server.

• Enable mTLS in edge certificates for the server. These are the certificates the server shares with the client for mTLS support. You need to bind these mTLS-enabled certificates to your CA set with ​Akamai​'s Certificate Provisioning System (CPS). These certificates need to be the same type (domain validated, organization validated, or extended validation) and format (standard TLS or enhanced TLS) of certificate you set up for client use in your CA set. Once done, you apply these certificates in your property when creating a secure hostname.

• Use TLS 1.3 and HTTP/3. When configuring mTLS in all your certificates, you should ensure that they use TLS 1.3 to avoid the security flaws with older TLS versions. Additionally, if you've set up your property using HTTP/3, it uses QUIC as the transport layer and TLS 1.3 is built-in, so lesser versions of TLS aren't supported.

📘

If you update an existing CA set, its changes aren't automatically applied in CPS or in Property Manager. See Caveats and known issues for complete information.

Apply basic support

Here, we'll apply a simple rule to deny requests to a specific hostname, if they don't properly apply mTLS.

1. Add a secure hostname to your property. Configure it to use the edge certificate where you've enabled mTLS for the server.

2. In the Property Configurations settings, click + Rules.

3. The Blank Rule Template is default selected. Click New Rule and give the rule an easy-to-recognize name, like Enforce mTLS.

4. Click Insert Rule.

5. In the Criteria options, click + Match. The match criterion defaults to Hostname > is one of.

6. In the empty field, enter the secure hostname you added.

7. In the Behaviors options, click + Behavior.

8. Type enforce in the Search available... field, select the Enforce mTLS settings behavior, and click Insert Behavior.

9. Configure the options in this behavior:

Apply custom handling

Here, we'll apply a collection of rules: a parent rule to enforce mTLS settings, and two nested child rules to apply custom handling for mismatched requests. Here's what you can expect to achieve with this:

• Successful requests passthrough client certificate information. A header will be sent to your origin server that contains details from the client's mTLS certificate. This lets you establish transitive trust between the client and your origin server.

• Special handling for requests that don't match. A request that doesn't match what you set will still be allowed. However, information will be included in the Log Delivery Service report for analysis.

1. Add Enforce mTLS settings

Start by adding a new parent rule to handle requests for mTLS.

1. Follow steps 1 - 8 in Apply basic support.

2. Configure the options in the Enforce mTLS settings behavior:

2. Add Client Certificate Authentication

Next, add a child rule that forwards client certificate details to your origin server as headers. You can configure your origin server to trust the headers, to enable transitive trust.

1. In the Property Configurations settings, click + Rules.

2. The Blank Rule Template is default selected. Click the New Rule field and give it an easy-to-recognize name, like Client cert auth.

3. Click Insert Rule. Your new rule is added to the bottom of the tree.

4. Click the handle () for the new rule entry and drag it below your Enforce mTLS rule to nest it as a child rule.

5. Click the rule to open it.

6. In the Criteria options, click + Match. Set the If options to:

   • Client certificate

   • Provided. Enabled.

   • Valid. The associated rule will only be applied if the client's mTLS certificate is valid.

7. In the Behaviors options, click + Behavior.

8. Type client cert in the Search available... field, select the Client Certificate Authentication behavior, and click Insert Behavior.

9. Configure the options in this behavior:

   Option	Description
   Enable	Enable this. Your property builds Client-Auth HTTP headers using information from the client to server (edge network) mTLS handshake and sends them to your origin server. You can configure your origin server to acknowledge these headers to enable transitive trust between itself and the requesting client.
   Complete client certificate	When ​Akamai​ builds the Client-to-Edge-HTTP-Auth header, it needs to include some form of the client's x.509 certificate. On. This includes the complete client certificate, in its binary (DER) format. DER-formatted certificates leave out the "BEGIN CERTIFICATE/END CERTIFICATE" statements and typically use the ".der" extension. Off. Select the individual Client certificate attributes to include.
   Client certificate attributes	With Complete client certificate set to Off, select from the list of certificate attributes to include them in the Client-to-Edge-HTTP-Auth header. Client certificate subject. The distinguished name of the client certificate's public key. Client certificate common name (CN). The common name (CN) that's been set in the client certificate. Client certificate SHA-256 fingerprint. An SHA-256 encrypted fingerprint of the client certificate. Client certificate issuer. The distinguished name of the entity that issued the certificate.
   Certificate validation status	Enable this. The current validation status of the client certificate in the Client-to-Edge-HTTP-Auth header. Configure your origin server to acknowledge the validity before it establishes trust—trust will only be established if the client certificate is currently valid.

3. Add Logging

Finally, we'll add a second child rule that generates log data for mismatched mTLS certificate requests.

1. In the Property Configurations settings, click + Rules.

2. The Blank Rule Template is default selected. Click the New Rule field and give it an easy-to-recognize name, like Log invalid certs.

3. Click Insert Rule. Your new rule is added to the bottom of the tree.

4. Click the handle () for the rule and drag it below your Enforce mTLS rule to nest it as a child rule.

5. Click the rule to open it.

6. In the Criteria options, click + Match. Set the If options to:

   • Client certificate

   • Provided. Enabled.

   • Invalid

   • Enforce mTLS settings results. Enabled.

   📘

   Ensure that Deny request in the Enforce mTLS settings behavior in the parent rule is disabled.

7. In the Behaviors options, click + Behavior.

8. Type log custom in the Search available... field, select the Log Custom Details behavior, and click Insert Behavior.

9. Configure the options in this behavior:

   Option	Description
   Include Custom Log Field	Enable this to include what's set in the Custom Log Field in the Log Delivery Service report.
   Custom Log Field	Specify the additional data field you want appended to each log line. You can add something like "invalid_mTLS" to make it easy to recognize log entries.

Caveats and known issues

Review what's here before setting up this support: