Client Certificate Authentication

📘

Currently, this feature is only available to select customers.

If you're using mutual authentication (mTLS), use this to send a header to your origin server that contains details from the mTLS certificate that was sent from the requesting client to the edge network.

How it works

With mTLS, both a requesting client and the ​Akamai​ edge server present a TLS certificate to the other, with each side validating the certificate during the "TLS handshake." Once both certificates are validated, the connection is allowed.

After the TLS handshake is approved, you can have this behavior pull various information from the client's successful certificate and forward it on to your origin server as header values. You can configure your origin server to review and trust the headers, to enable transitive trust.

📘

This works with Enforce mTLS settings

This behavior is designed to use the Client Certificate match, serving in a child rule to a parent rule that includes the Enforce mTLS settings behavior. The Enforce mTLS behavior is what's used to check the certificates and validate the certificates during the TLS handshake.

For an example of its use, see the Enforce mTLS settings behavior.

Features and options

FieldWhat it does

Enable

With this enabled, an edge server builds the Client to Edge HTTP Authentication headers using information from the client to edge server mTLS handshake and sends it to your origin server.

Complete client certificate

Enable this to include the complete client certificate in the AKAMAI-CC-DER header, in its binary (DER) format. These files typically use the ".der" extension. Disable it to select specific client-certificate details, using the “Client certificate attributes" option. You can decode the header value as a ”:”-delimited Byte Sequence, where the value of the binary data is a DER-encoded x509 cert. See the Byte Sequence ABNF rule in RFC-8941.

Client certificate attributes

Use these options to select specific client's x.509 certificate attributes in the header, instead of including the entire certificate. To use this field, make sure you set the “Complete client certificate” to Off.

  • Client certificate Subject. The distinguished name of the client certificate's public key. ​Akamai​ sends it in the AKAMAI-CC-SUBJECT header. You can decode the header value as a ”:”-delimited Byte Sequence. See the Byte Sequence ABNF rule in RFC-8941.

  • Client certificate common name (CN). The common name (CN) that's been set in the client certificate. ​Akamai​ sends it in the AKAMAI-CC-CN header. ​Akamai​ sends the first CN, very rarely there are more than one CNs in the X.509 certificate’s Subject attribute. If CN is not present in Subject or if the first CN is empty, then the value of the header is an empty string. You can decode the header value as a ”:”-delimited Byte Sequence. See the Byte Sequence ABNF rule in RFC-8941.

  • Client certificate SHA-256 fingerprint. An SHA-256 fingerprint of the client certificate. ​Akamai​ sends it in the AKAMAI-CC-FINGERPRINT-SHA256 header. The header values are compatible with the RFC-8941 Token ABNF, so no intermediate encoding is necessary besides hexadecimal encoding.

  • Client certificate issuer. The distinguished name of the entity that issued the certificate. ​Akamai​ sends it in the AKAMAI-CC-ISSUER header. You can decode the header value as a ”:”-delimited Byte Sequence. See the Byte Sequence ABNF rule in RFC-8941.

Certificate validation status

With this enabled, the edge server includes the current validation status of the client certificate in the AKAMAI-CC-STATUS header. Use this as an added measure of security—have your origin server check this validity before it establishes trust with the requesting client. The AKAMAI-CC-STATUS header values are compatible with the RFC-8941 Token ABNF, so no intermediate encoding is necessary.

The client cert validation status in AKAMAI-CC-STATUS uses the machine-readable OpenSSL error names.
These are the possible values:

  • successful verification: X509_V_OK
  • error in verification: X509_V_ERR_*
  • absence of the client cert: AKA_ERR_NO_CLIENT_CERT