📘

Limited Availability

This feature is only available to select customers and now it includes some functionality from the Client Certificate Authentication behavior. Talk to your account team about eligibility.

The transport layer security (TLS) protocol is used to secure connections between a client and server during what's called the "TLS handshake”. With a standard TLS-secured web connection, the client validates the identity of the server before allowing communications which is effectively the "S" in "HTTPS". With a mutual TLS-secured web connection, 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 certificate authenticity. Once verified, the identity information is used to authorize additional communication requests between the two.

Before you begin

There are a few prerequisites you need to meet before adding mTLS support to your delivery 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. We verify the certificates presented by clients connecting to your secure hostnames against a CA defined in one of these CA sets.

• Enable mTLS in edge certificates for the server. These are the certificates the ​Akamai​ server shares with the client for mTLS support. You need to bind these mTLS-enabled certificates with your CA set, using ​Akamai​'s Certificate Provisioning System (CPS).

• Use TLS 1.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. If you've set up your property using HTTP/3, TLS 1.3 is built-in, so the older versions of TLS aren't supported.

📘

See Caveats and known issues for more information about the interactions between mETs, CPS and Property Manager.

Why you need it

The Enforce mTLS settings behavior is a part of the authorization logic for your delivery property. It ensures requests processed by your property are coming from TLS connections set in an mTLS configuration you've applied.

The ​Edge certificate and its settings are bound to one or more of your hostnames, possibly across multiple properties. You can set it up a property to support requests from multiple edge certificates, each with varying TLS settings to support different use cases. For example:

• An Edge certificate with a specific hostname with mTLS implemented.

• An edge certificate that uses a wildcard hostname without mTLS implemented. In this scenario, the Enforce mTLS settings behavior's settings can be applied to enforce mTLS for requests to the specific hostname, but they wouldn't apply to requests to other hostnames that match the wildcard hostname.

How it works

A client makes a connection to a particular edge certificate on the ​Akamai​ network and the client certificate, if presented, is validated. The HTTP request from the client is sent over this connection and processed by your property where this behavior is processed.

Configure this behavior to ensure the client certificate validation was successful. If there's a mismatch, you can apply custom error handling.

By default, this behavior flags an error if any of these situations occur:

• The client doesn't present a certificate.
• The client presents an invalid certificate. For example:
  • The certificate has expired.
  • The certificate can't be verified by any CA in the defined CA set(s).
  • The certificate doesn't pass OCSP checks if specified.

Features and options

Check client certificate at edge

❗️

If you select Continue, and don't subsequently deny the request using the Client certificate match, the request is processed as normal. If the request goes forward to your origin, you can return an error from there, but if the client requests content that is in the ​Akamai​ server cache, that content is served.

📘

If you select Deny Request, there is no forward request to your origin, so you cannot monitor for these invalid requests at your origin.

Send client certificate details to origin

These options only apply if the When checks fail option is set to Continue and if the request is not subsequently denied using the Client certificate match.

❗️

If the request is for content that is in the ​Akamai​ server cache, it is returned, and no request is made to your origin.

If a request is forwarded to your origin, it includes the Akamai-CC-Status header with one of the following values:

• X509_V_OK. The presented client certificate is valid.
• AKA_ERR_NO_CLIENT_CERT. The client certificate is missing.
• X509_V_ERR_* . For multiple values. The presented client certificate is invalid.

Additional headers may be sent to your origin depending on the options selected below. Note that the additional headers should only be trusted by the origin if the Akamai-CC-Status header shows that the client certificate is valid. In all other cases, you can't rely on the other headers.

Implementation

This section offers example workflows you can follow to add this support.

Apply standard support

Here, we'll apply a single rule to deny requests if the requesting client doesn't present a valid client certificate. This is the most common implementation and is the suggested best practice implementation.

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

2. Add a new top-level rule with no parent rules and call it Enforce mTLS.

3. Optionally add a Hostname match to specify your secure hostname if you wish to apply mTLS enforcement to only that hostname.

4. Add the Enforce mTLS settings behavior. Specify the default options as shown above and the CA trust set configured in your Edge certificate.

In this scenario, the following occurs:

• Requests which don't present a client certificate are denied.
• Requests which present an invalid certificate are denied.
• Requests which present a valid client certificate are processed.

📘

Note that ​Akamai​ denies requests which don't present a client certificate or which present an invalid certificate, so no forward request is made to your origin and you have no way of logging these bad requests at your origin.

Apply custom handling

Here, we'll apply a more complex collection of rules: a parent rule to check mTLS settings, and two child rules to apply custom handling for certain invalid requests. This example allows you to log both valid and invalid certificates at your origin and also in ​Akamai​.

• Successful requests pass through client certificate information. Headers are sent to your origin server that contain details from the client certificate. This lets you establish transitive trust between the client and your origin server.

• Special handling for requests that don't match. A request with a missing client certificate is denied. A request with an invalid client certificate is still allowed, but information is included in the Log Delivery Service report for analysis.

📘

When implementing custom handling this way, be aware that the request is processed and a forward request may be made to your origin, even with an invalid or potentially malicious client certificate.

1. Add a new parent rule to handle requests for mTLS

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

1. Follow steps 1 - 4 in Apply standard support.

2. Configure the following two options in the Enforce mTLS settings behavior, and the CA trust set configured in your Edge certificate. Options not specified here should use the default values:

2. Add a child rule that denies requests where a client certificate was not presented

1. Add a child rule to the above parent rule and call it Missing client cert.
2. Add the Client certificate match. Set the option to Cert is Missing.
3. Add the Control Access behavior and set the Reason ID option to Missing client cert.

You can add other behaviors in the Missing client cert child rule. For example, you can write invalid access attempts to DataStream, or you can send a formatted error page retrieved from NetStorage rather than the basic error that is returned as a result of the Control Access behavior.

3. Add logging

Finally, we'll add a second child rule that generates log data for all requests where a client certificate was presented but the certificate was invalid.

1. Add a child rule to the above parent rule and call it Log invalid certs.
2. Add the Client certificate match. Set the option to Cert is Present but Invalid.
3. Add the Log Custom Details behavior
   1. Enable the Include Custom Log Field option.
   2. Set the Custom Log option to invalid_client_mtls.

You can add other behaviors in the Log invalid certs child rules, in addition to the Include Log Custom option. For example, you can write invalid access attempts to DataStream.

In this custom handling scenario, the following occurs:

• Requests which don't present a client certificate are denied.
• Requests which present a valid client certificate are processed.
• Requests which present an invalid certificate are processed and the error is logged by the edge server.

For requests which go to your origin, the origin can check the Akamai-CC-Status request header to determine whether the client presented a valid or an invalid client certificate. In the latter case, you can return an error page from your origin. If the presented certificate is valid, your origin can further refine and implement authorization policies based on the value of the Akamai-CC-Subject and Akamai-CC-Issuer request headers.

Caveats and known issues

Review what's here before setting up this support: