📘

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 (mTLS) 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.

1. Create a client CA set

A certificate authority (CA) set is a collection of certificates that you use to verify the authenticity of clients requesting access to your content on the ​Akamai​​ edge network. It's specifically used to establish mTLS-authenticated connections. You'll use ​Akamai​'s mTLS Edge Truststore application for this.

Before you begin

You need to create the certificates you want to use for the client-to-​Akamai​ edge network connection in the mTLS transaction. You can use any trusted certificate authority (Let's Encrypt, DigiCert) to generate these certificates. When you add a certificate to a CA set, the mTLS Edge Truststore validates it against these requirements:

• It needs to be a correctly-formed x509 (PEM-encoded) certificate.

• It has valid x509 CA bits set.

• It's within its validity period. (Make sure it's not near expiration.)

• It's a self-signed root certificate or an intermediate certificate.

• It uses the SHA-256 signature hash algorithm or better.

Create a new CA set

With your certificates ready, create a CA set to add them for use with mTLS:

1. Access ​Akamai​ Control Center.

2. Select ☰ > CDN > mTLS Edge Truststore.

3. Click New CA certificate set.

4. Give your CA set a name and optionally, enter a description.

📘

Make sure you're happy with the name you choose for your CA set. Once created, you can't change it. Also, make note of the name. You'll need it later.

5. Click Submit. The CA set appears under CA Certificate sets.

6. With your new set selected, click + Create Version 1 to create the first version of your CA set.

7. Click Add certificates and select a method to add a certificate to your set:

   • Drag and drop. Pick a file from your local machine and drag it to the Paste certificate PEM(s) here field. You can select multiple certificate files to drag and drop.

   • Click browse. Navigate to and select the certificate file on your local machine. You can multi-select more than one certificate file to add.

   • Copy/Paste. Open the PEM-encoded certificate in a text editor and copy its entire contents. Paste into the Paste certificate PEM(s) here field.

8. Click Validate and add to version. If you see an error message, check that your certificates meet the validation requirements and re-add them.

9. If necessary, repeat steps 7-8 to add more certificates.

10. Leave all other options at their default setting and click Create version.

Activate your CA set

Get your new CA set activated on the ​Akamai​ networks. It needs to be active on the same network where the server's mTLS-enabled edge certificate is active. The staging network is used for testing and production network is used to go live.

1. in the mTLS Edge Truststore, select the CA set you just created.

2. Select the CA set version to use.

3. Click ... under Actions and select Activate.

4. Review your CA set's details to make sure everything is OK.

5. Click the Activate version... button for the applicable network, or click both.

📘

Activation time

This varies based on the ​Akamai​ network:

• Staging. Up to 2 hours.

• Production. Up to 30 minutes.

2. Set up a server certificate

This is the edge certificate your property shares with the client for mTLS support. You need to enable mTLS support in this certificate and then bind it to your CA set with ​​Akamai​'s Certificate Provisioning System (CPS).

1. Access ​Akamai​ Control Center.

2. Select ☰ > CDN > Certificates.

3. Find your certificate based on its Common name and click ... under Actions and select View and edit deployment settings.

📘

If necessary, create a new certificate using your domain. Make sure it's the same type (domain validated, organization validated, or extended validation) and format (standard TLS or enhanced TLS) you used for the client certificates in your CA set.

4. In 4 - Mutual Authentication, click Edit and set these options:

   • Certificate Set. Select the CA set you created and activated.

   • OCSP. Enable this if the certificates you've included in your CA set use the online certificate support protocol (OCSP). OCSP can determine the X.509 certificate revocation status during the TLS handshake.

   • Send CA list to client. With this enabled, the edge servers will also send the names of the CA sets you've included in your edge certificate back to the requesting client.

5. Click Submit to update your edge certificate.

3. Enforce mTLS

In the next phase of the process, update your property configuration in Property Manager to apply support for mTLS.

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: