Adding the CloudFront HTTP headers - Amazon CloudFront
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Adding the CloudFront HTTP headers

You can configure CloudFront to add specific HTTP headers to the requests that CloudFront receives from viewers. The values of these HTTP headers are based on characteristics of the viewer request. The headers can provide information about the viewer's device type, IP address, geographic location, request protocol (HTTP or HTTPS), HTTP version, and TLS connection details.

With these headers, your origin or your edge function can receive information about the viewer without the need for you to write your own code to determine this information. If your origin returns different responses based on the information in these headers, you can include them in the cache key so that CloudFront caches the responses separately. For example, your origin might respond with content in a specific language based on the country that the viewer is in, or with content tailored to a specific device type. Your origin might also write these headers to log files, which you can use to determine information about where your viewers are, which device types they're on, and more.

To include these headers in the cache key, use a cache policy. For more information, see Controlling the cache key and Understanding the cache key.

To receive these headers at your origin but not include them in the cache key, use an origin request policy. For more information, see Controlling origin requests.

Headers for determining the viewer's device type

You can add the following headers to determine the viewer's device type. Based on the value of the User-Agent header, CloudFront sets the value of these headers to true or false. If a device falls into more than one category, more than one value can be true. For example, for some tablet devices, CloudFront sets both CloudFront-Is-Mobile-Viewer and CloudFront-Is-Tablet-Viewer to true.

  • CloudFront-Is-Android-Viewer – Set to true when CloudFront determines that the viewer is a device with the Android operating system.

  • CloudFront-Is-Desktop-Viewer – Set to true when CloudFront determines that the viewer is a desktop device.

  • CloudFront-Is-IOS-Viewer – Set to true when CloudFront determines that the viewer is a device with an Apple mobile operating system, such as iPhone, iPod touch, and some iPad devices.

  • CloudFront-Is-Mobile-Viewer – Set to true when CloudFront determines that the viewer is a mobile device.

  • CloudFront-Is-SmartTV-Viewer – Set to true when CloudFront determines that the viewer is a smart TV.

  • CloudFront-Is-Tablet-Viewer – Set to true when CloudFront determines that the viewer is a tablet.

Headers for determining the viewer's location

You can add the following headers to determine the viewer's location. CloudFront determines the values for these headers based on the viewer's IP address. For non-ASCII characters in these headers' values, CloudFront percent-encodes the character according to section 1.2 of RFC 3986.

  • CloudFront-Viewer-Address – Contains the IP address of the viewer that sent the request to CloudFront, and the source port of the request. For example, a header value of 198.51.100.10:46532 means the viewer's IP address is 198.51.100.10 and the request source port is 46532.

    Note

    You can add CloudFront-Viewer-Address in an origin request policy, but not in a cache policy.

  • CloudFront-Viewer-Country – Contains the two-letter country code for the viewer's country. For a list of country codes, see ISO 3166-1 alpha-2.

When you add the following headers, CloudFront applies them to all requests except those that originate from the Amazon network:

  • CloudFront-Viewer-City – Contains the name of the viewer's city.

  • CloudFront-Viewer-Country-Name – Contains the name of the viewer's country.

  • CloudFront-Viewer-Country-Region – Contains a code (up to three characters) that represent the viewer's region. The region is the first-level subdivision (the broadest or least specific) of the ISO 3166-2 code.

  • CloudFront-Viewer-Country-Region-Name – Contains the name of the viewer's region. The region is the first-level subdivision (the broadest or least specific) of the ISO 3166-2 code.

  • CloudFront-Viewer-Latitude – Contains the viewer's approximate latitude.

  • CloudFront-Viewer-Longitude – Contains the viewer's approximate longitude.

  • CloudFront-Viewer-Metro-Code – Contains the viewer's metro code. This is present only when the viewer is in the United States.

  • CloudFront-Viewer-Postal-Code – Contains the viewer's postal code.

  • CloudFront-Viewer-Time-Zone Contains the viewer's time zone, in IANA time zone database format (for example, America/Los_Angeles).

Other CloudFront headers

You can add the following headers to determine the protocol and HTTP version of the viewer's request:

  • CloudFront-Forwarded-Proto – Contains the protocol of the viewer's request (HTTP or HTTPS).

  • CloudFront-Viewer-Http-Version – Contains the HTTP version of the viewer's request.

  • CloudFront-Viewer-TLS – Contains the SSL/TLS version, the cipher, and information about the SSL/TLS handshake that was used for the connection between the viewer and CloudFront. The header value is in the following format:

    SSL/TLS_version:cipher:handshake_information

    For handshake_information, the header can contain the following values:

    • fullHandshake – A full handshake was performed for the SSL/TLS session.

    • sessionResumed – A previous SSL/TLS session was resumed.

    • connectionReused – A previous SSL/TLS connection was reused.

    The following are some example values for this header:

    TLSv1.3:TLS_AES_128_GCM_SHA256:sessionResumed
    TLSv1.2:ECDHE-ECDSA-AES128-GCM-SHA256:connectionReused
    TLSv1.1:ECDHE-RSA-AES128-SHA256:fullHandshake
    TLSv1:ECDHE-RSA-AES256-SHA:fullHandshake

    For the full list of possible SSL/TLS versions and ciphers that can be in this header value, see Supported protocols and ciphers between viewers and CloudFront.

    Note

    You can add CloudFront-Viewer-TLS in an origin request policy, but not in a cache policy.