Using CloudFront TLS Headers to Troubleshoot HTTPS Connections

Avoid forwarding every available viewer header without a clear requirement. Forwarding only the required values keeps the request configuration easier to manage.

Step 3: Attach the Policy to the Cache Behavior

Save the origin request policy and attach it to the selected cache behavior.

An origin request policy forwards selected headers to the origin without automatically adding them to the cache key.

This distinction matters.

TLS and ISP information is useful for diagnostics, but it normally should not create separate cached copies of the same application response.

If an application genuinely returns different content based on a forwarded header, review the cache-key design carefully to avoid serving an incorrect response to another viewer.

Step 4: Deploy and Verify the Configuration

Save the distribution changes and wait until the distribution deployment completes.

Send a new HTTPS request through CloudFront and inspect the corresponding request at the origin.

The expected headers should be available when CloudFront forwards them.

Remember that these headers describe the viewer-to-CloudFront connection, not the CloudFront-to-origin TLS connection.

Reading CloudFront TLS Headers in a Node.js Application

Once CloudFront forwards the headers, an application can capture them for diagnostics.

The following Express.js example reads the TLS version, cipher suite, handshake information, and ISP.

const express = require("express");

const app = express();

app.get("/api/connection-info", (req, res) => {
    const tlsHeader =
        req.get("CloudFront-Viewer-TLS");

    const isp =
        req.get("CloudFront-Viewer-ISP");

    const tlsDetailsHeader =
        req.get("CloudFront-Viewer-TLS-Details");

    let tlsDetails = null;

    try {
        if (tlsDetailsHeader) {
            tlsDetails = JSON.parse(tlsDetailsHeader);
        }
    } catch (error) {
        console.error("Invalid TLS details header");
    }

    const tlsParts = tlsHeader
        ? tlsHeader.split(":")
        : [];

    res.json({
        tlsVersion: tlsParts[0] || "Unknown",
        cipherSuite: tlsParts[1] || "Unknown",
        handshakeType: tlsParts[2] || "Unknown",
        isp: isp || "Unknown",
        tlsDetails
    });
});

app.listen(3000, () => {
    console.log("Application started");
});

The endpoint returns diagnostic information in a structured JSON response.

For example:

{
  "tlsVersion": "TLSv1.3",
  "cipherSuite": "TLS_AES_128_GCM_SHA256",
  "handshakeType": "sessionResumed",
  "isp": "Example Network",
  "tlsDetails": {
    "tlsVersion": "TLSv1.3",
    "keyExchange": "X25519"
  }
}

The response is illustrative.

In a production application, avoid exposing detailed connection information through a publicly accessible endpoint. Store the information in application logs or a restricted diagnostic service instead.

Also, do not assume that a forwarded header is trustworthy if users can access the origin directly. Restrict origin access to CloudFront and ensure that the application only trusts headers supplied through the intended distribution path.

Using TLS Information to Investigate Connection Problems

Let's consider a practical example.

An application receives reports that users from one network provider experience intermittent HTTPS connection problems.

The development team can collect the viewer ISP and TLS information for successful requests and compare it with CloudFront access logs and application logs.

A simplified investigation might look like this:

There is an important limitation: these headers are available only after CloudFront has established an HTTP request from the viewer.

If a TLS handshake fails before HTTP communication is established, the request cannot reach the origin with these headers.

For those failures, use CloudFront monitoring, client-side diagnostics, and other available connection-level evidence.

Troubleshooting Common Configuration Problems

TLS headers are missing at the origin

First, verify that the headers are included in the origin request policy attached to the correct cache behavior.

Also confirm that the distribution deployment has completed.

ISP information is unavailable

Check whether the request is coming from an expected viewer network and whether the relevant header is configured.

ISP information may not be sufficient to identify the organization behind every network address.

TLS details cannot be parsed

The TLS details header contains JSON. Check the raw value before parsing it.

Use error handling so malformed or missing diagnostic information does not break the main application request.

CloudFront and origin TLS versions are different

This is expected in some architectures.

The viewer-to-CloudFront connection and CloudFront-to-origin connection are separate TLS sessions.

Inspect the correct connection when investigating a protocol mismatch.

Origin receives unexpected header values

Review whether the origin can be accessed directly and whether client-supplied headers can reach application logic.

Use origin access restrictions and trusted CloudFront forwarding configuration to prevent untrusted values from being treated as authoritative.

Best Practices for Production Applications

1. Forward only the headers required for troubleshooting and monitoring.
2. Use an origin request policy when the information is needed at the origin but should not affect the cache key.
3. Record TLS version, cipher suite, and ISP alongside request IDs and timestamps.
4. Avoid storing sensitive diagnostic information longer than necessary.
5. Restrict direct access to the origin server.
6. Validate forwarded header values before using them in application logic.
7. Compare TLS information with CloudFront access logs and application errors.
8. Monitor connection patterns across different network providers.
9. Use JA3 and JA4 fingerprints as supporting signals rather than treating them as proof of malicious activity.
10. Keep the viewer-to-CloudFront and CloudFront-to-origin TLS configurations separate during investigations.

Advantages and Disadvantages of CloudFront TLS Headers

Advantages

• Provide visibility into the TLS connection negotiated by viewers.
• Help identify differences in TLS versions and cipher suites.
• Support ISP-based troubleshooting.
• Provide additional information about cryptographic key exchange.
• Can be inspected by the origin application or supported edge functions.
• Help security teams investigate unusual client connection patterns.

Disadvantages

• Do not provide information about TLS handshakes that fail before an HTTP request is established.
• Require origin request policy configuration when forwarding headers to the origin.
• Do not independently identify the root cause of network failures.
• Require careful handling to avoid trusting unverified headers.
• Additional logging can increase storage and monitoring costs.

Summary

Amazon CloudFront provides several viewer-related headers that help developers investigate HTTPS connection behavior.

The CloudFront-Viewer-TLS header identifies the negotiated TLS version, cipher suite, and handshake information. CloudFront-Viewer-ISP helps compare requests across network providers, while CloudFront-Viewer-TLS-Details provides additional cryptographic information, including key exchange and signature details.

By configuring an origin request policy, developers can forward these values to their application and include them in diagnostic logs.

These headers are particularly useful when investigating client compatibility, network-specific problems, and cryptographic migration. However, they cannot explain every connection failure, especially failures that occur before the TLS handshake completes.

Combining CloudFront headers with access logs, application monitoring, and origin security controls provides a more complete approach to troubleshooting HTTPS connections in production.