Protect connections with mTLS
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 2.
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:
-
Access Akamai Control Center.
-
Select ☰ > CDN > mTLS Edge Truststore.
-
Click New CA certificate set.
- 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.
-
Click Submit. The CA set appears under CA Certificate sets.
-
With your new set selected, click + Create Version 1 to create the first version of your CA set.
-
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.
-
-
Click Validate and add to version. If you see an error message, check that your certificates meet the validation requirements and re-add them.
-
If necessary, repeat steps 7-8 to add more certificates.
-
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.
-
in the mTLS Edge Truststore, select the CA set you just created.
-
Select the CA set version to use.
-
Click ... under Actions and select Activate.
-
Review your CA set's details to make sure everything is OK.
-
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).
-
Access Akamai Control Center.
-
Select ☰ > CDN > Certificates.
-
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.
-
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.
-
- 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.
-
Add a secure hostname to your property. Configure it to use the edge certificate where you've enabled mTLS for the server.
-
In the Property Configurations settings, click + Rules.
-
The Blank Rule Template is default selected. Click New Rule and give the rule an easy-to-recognize name, like Enforce mTLS.
-
Click Insert Rule.
-
In the Criteria options, click + Match. The match criterion defaults to Hostname > is one of.
-
In the empty field, enter the secure hostname you added.
-
In the Behaviors options, click + Behavior.
-
Type
enforce
in the Search available... field, select the Enforce mTLS settings behavior, and click Insert Behavior. -
Configure the options in this behavior:
Option | Description |
---|---|
Enforce certificate authority sets | Enable this. Your property will validate that the settings in this behavior apply. |
Certificate authority sets | Select the CA sets you created with Akamai's mTLS Edge Truststore, and bound to your edge certificate in CPS. |
OCSP Status | Enable this if the certificates you're using in your CA set (for client requests) and your edge certificates in CPS (for the server response) use the online certificate support protocol (OCSP). OCSP can determine the X.509 certificate revocation status during the TLS handshake. |
Deny request | Enable this. Any request for the specified hostname that doesn't match the settings you've applied in this behavior will be denied. A request doesn't match if:
If a request matches on both, it's allowed. |
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.
-
Follow steps 1 - 8 in Apply basic support.
-
Configure the options in the Enforce mTLS settings behavior:
Option | Description |
---|---|
Enforce certificate authority sets | Enable this. Your property will validate that the settings in this behavior apply. |
Certificate authority sets | Select the CA sets you created with Akamai's mTLS Edge Truststore, and bound to your edge certificate in CPS. |
OCSP Status | Enable this if the certificates you're using in your CA set (for client requests) and your edge certificates in CPS (for the server response) use the online certificate support protocol (OCSP). OCSP can determine the X.509 certificate revocation status during the TLS handshake. |
Deny request | Disable this. Any request that matches the settings you've applied in this behavior will be allowed. A request that doesn't match the settings will be allowed, too. But, you'll incorporate custom handling for these requests, through the other rules in the behavior. A request doesn't match settings if either of the following apply:
|
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.
-
In the Property Configurations settings, click + Rules.
-
The Blank Rule Template is default selected. Click the New Rule field and give it an easy-to-recognize name, like Client cert auth.
-
Click Insert Rule. Your new rule is added to the bottom of the tree.
-
Click the handle () for the new rule entry and drag it below your Enforce mTLS rule to nest it as a child rule.
-
Click the rule to open it.
-
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.
-
-
In the Behaviors options, click + Behavior.
-
Type
client cert
in the Search available... field, select the Client Certificate Authentication behavior, and click Insert Behavior. -
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.
-
In the Property Configurations settings, click + Rules.
-
The Blank Rule Template is default selected. Click the New Rule field and give it an easy-to-recognize name, like Log invalid certs.
-
Click Insert Rule. Your new rule is added to the bottom of the tree.
-
Click the handle () for the rule and drag it below your Enforce mTLS rule to nest it as a child rule.
-
Click the rule to open it.
-
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.
-
-
In the Behaviors options, click + Behavior.
-
Type
log custom
in the Search available... field, select the Log Custom Details behavior, and click Insert Behavior. -
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:
Issue | Detail |
---|---|
Changes aren't automatically applied | If you make an update to your CA set in the mTLS Edge Truststore, ensure you make the applicable changes to your property here in Property Manager, and to any certificates in the Certificate Provisioning System (CPS). For example, if you remove a CA set from the mTLS Edge Truststore, you also need to unbind the CA set from the certificate in CPS and remove the CA Set from your property here in the Enforce mTLS settings behavior. If you don’t, you could see disablement of service for requests for your property. |
TLS 1.3 doesn't support renegotiation | If you need to use client certificates after the TLS handshake via renegotiation, you'll need to use a legacy version. This is because TLS 1.3 doesn't support renegotiation. For example, if you're using mTLS and you're restricting requests to certain folders, based on a URL path in the request—rather than all content on your origin server—a TLS renegotiation may be triggered. Connections using TLS 1.3 don't support renegotiation because it's a potential cyber threat. The renegotiation is just one more point in the transaction that a hacker can exploit. |
Certificates are subject to regular revocation | Based on the type of certificate you're using, the certificate authority that validates them will revoke them after a set amount of time. (For example a domain validated certificate has a life cycle of 90 days.) Akamai edge servers check a certificate's revocation status through OCSP. As a best practice, enable OCSP in your client certificates and your edge certificate for your server. Then, enable the OCSP Status option when configuring the Enforce mTLS settings behavior. Many web browsers don't check the revocation status for certificates via OCSP, but this doesn't affect the mTLS use cases for certificates. |
Use SHA-256 encryption | As a best practice, all certificates you use for mTLS should have their certificate authority signature component encrypted using at least SHA-256 encryption. While the mTLS Edge Truststore application offers an option to support SHA-1 level encrypted signatures, SHA-256 offers better protection. All mTLS certificates need to use the same level of signature encryption. |
SSLv3 isn't supported | Any certificate you use for mTLS can't have any of its slots configured to use SSLv3. This is an antiquated protocol that is supported in some legacy environments. |
The shared certificate isn't supported | You can't configure an edge hostname and secure it with Akamai's shared certificate. This format doesn't support mTLS. |
Updated about 2 months ago