Amazon CloudFront
Developer Guide (API Version 2016-09-29)

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

Forwarding Custom Headers to Your Origin

You can configure CloudFront to include custom headers whenever it forwards a request to your origin. You can specify the names and values of custom headers for each origin, both for custom origins and for Amazon S3 buckets.

Note

Forwarding custom headers only applies to web distributions.

Custom headers have a variety of uses, such as the following:

  • You can identify the requests that are forwarded to your custom origin by CloudFront. This is useful if you want to know whether users are bypassing CloudFront or if you're using more than one CDN and you want information about which requests are coming from each CDN. (If you're using an Amazon S3 origin and you enable Amazon S3 server access logging, the logs don't include header information.)

  • If you've configured more than one CloudFront distribution to use the same origin, you can specify different custom headers for the origins in each distribution and use the logs for your web server to distinguish between the requests that CloudFront forwards for each distribution.

  • If some of your users use viewers that don't support cross-origin resource sharing (CORS), you can configure CloudFront to forward the Origin header to your origin. That will cause your origin to return the Access-Control-Allow-Origin header for every request.

  • You can use custom headers and, optionally, signed URLs or signed cookies, to control access to content on a custom origin. If you configure your custom origin to respond to requests only if they include a custom header, you can prevent users from bypassing CloudFront and submitting requests directly to your origin. For more information, see Restricting Access to Files on Custom Origins.

Configuring CloudFront to Forward Custom Headers to Your Origin

To configure a web distribution to forward custom headers to your origin, you update the configuration of the origin by using one of the following methods:

CloudFront console

When you create or update a distribution, specify header names and values in the Origin Custom Headers settings. For more information, see Creating a Distribution.

CloudFront API

For each origin that you want to forward custom headers to, add header names and values to the CustomHeaders section of the DistributionConfig complex type. For more information, see CreateDistribution (to create a new distribution) or UpdateDistribution (to update an existing distribution).

If the header names and values that you specify are not already present in the viewer request, CloudFront adds them. If a header is present, CloudFront overwrites the header value before forwarding the request to the origin.

For the current limits related to forwarding custom headers to the origin, see Limits.

Custom Headers that CloudFront Can't Forward to Your Origin

You can't configure CloudFront to forward the following custom headers to your origin.

Cache-Control

Proxy-Authorization

Connection

Proxy-Connection

Content-Length

Range

Cookie

Request-Range

Host

TE

If-Match

Trailer

If-Modified-Since

Transfer-Encoding

If-None-Match

Upgrade

If-Range

Via

If-Unmodified-Since

Headers that begin with X-Amz-*

Max-Forwards

Headers that begin with X-Edge-*

Pragma

X-Real-Ip

Use Custom Headers for Cross-Origin Resource Sharing (CORS)

You can configure CloudFront to always forward specific headers to your origin to accommodate viewers that don't automatically include those headers in requests. You also need to configure CloudFront to respect CORS settings. For more information, see Configuring CloudFront to Respect CORS Settings.

Use Custom Headers to Restrict Access to Content

You can configure CloudFront to always forward specific headers to your origin as part of a configuration to restrict access to content on your origin. For more information, see Restricting Access to Files on Custom Origins.

Configure CloudFront to Forward Authorization Headers

When it forwards requests to your origin, CloudFront removes some headers by default, including authorization headers. If you want to always forward authorization headers for a specific cache behavior, be sure that you whitelist the headers for that cache behavior. To learn more, see Whitelist Headers.