Helper methods for mutual TLS

CloudFront provides mTLS-specific helper functions in the cf.mtls namespace for viewer request functions. These functions rename, reformat, or combine client certificate headers before forwarding the request to your origin.

import cf from "cloudfront";

cf.mtls.renameClientCertHeaders

Renames certificate metadata headers to custom header names.

cf.mtls.renameClientCertHeaders({
    "CloudFront-Viewer-Cert-Pem": "X-Client-Cert",
    "CloudFront-Viewer-Cert-Serial-Number": "X-Client-Cert-Serial",
    "CloudFront-Viewer-Cert-Issuer": "X-Client-Cert-Issuer",
});

Allowed source headers:

• CloudFront-Viewer-Cert-Pem

• CloudFront-Viewer-Cert-Serial-Number

• CloudFront-Viewer-Cert-Issuer

• CloudFront-Viewer-Cert-Subject

• CloudFront-Viewer-Cert-Validity

• CloudFront-Viewer-Cert-Present

• CloudFront-Viewer-Cert-Sha256

• Client-Cert

• Client-Cert-Chain

cf.mtls.renamePemHeaders

Renames PEM certificate headers and optionally reformats the certificate encoding.

cf.mtls.renamePemHeaders({
    "Client-Cert": {
        "newHeaderName": "X-Leaf-Cert",
        "pemCertFormatInfo": {
            "certHeader": "-----CUSTOM HEADER-----",
            "certFooter": "-----CUSTOM FOOTER-----",
            "certEndMarker": "",
            "keepNewlinesInCertData": true
        }
    },
    "Client-Cert-Chain": {
        "newHeaderName": "X-Intermediate-Certs",
        "pemCertFormatInfo": {
            "certHeader": "-----CUSTOM HEADER-----",
            "certFooter": "-----CUSTOM FOOTER-----",
            "certEndMarker": "",
            "keepNewlinesInCertData": true
        }
    }
});

Allowed source headers:

• In passthrough mode: Client-Cert, Client-Cert-Chain

• In required/optional mode: Cloudfront-Viewer-Cert-PEM

pemCertFormatInfo fields:

For Cloudfront-Viewer-Cert-PEM:

• certHeader replaces -----BEGIN CERTIFICATE-----.

• certFooter replaces -----END CERTIFICATE-----.

• certEndMarker sets a custom string after the certFooter.

• keepNewlinesInCertData (default: true) preserves newlines in base64 data when true.

For Client-Cert and Client-Cert-Chain:

• certHeader replaces :.

• certFooter replaces :.

• certEndMarker sets a custom string after the certFooter.

• keepNewlinesInCertData (default: false) preserves newlines in base64 data when true.

cf.mtls.combinePemHeaders

Combines Client-Cert and Client-Cert-Chain into a single header containing the full certificate chain.

cf.mtls.combinePemHeaders({
    "newHeaderName": "X-Full-Chain",
    "pemCertFormatInfo": {
        "certHeader": "-----BEGIN CERTIFICATE-----",
        "certFooter": "-----END CERTIFICATE-----",
        "certEndMarker": "\n",
        "keepNewlinesInCertData": false
    }
});

certEndMarker sets the delimiter between certificates.

Note

• These helper functions can be used in all mTLS modes (required, optional, and passthrough). However, cf.mtls.combinePemHeaders only has effect in passthrough mode — in required and optional modes, the Client-Cert and Client-Cert-Chain headers are not present, so the function is a no-op.

• If cf.mtls.* methods and cf.updateRequestOrigin() with customHeaders target the same header name, CloudFront returns a 502 error.

• In Passthrough mode, CloudFront drops any incoming Client-Cert or Client-Cert-Chain headers and re-adds them from the actual client certificate.

• CloudFront doesn't present the full raw PEM certificate contents in any edge functions.