Policy details (metadata)CORS headers Security headers Custom headers Remove headers Server-Timing header

Understand response headers policies

You can use a response headers policy to specify the HTTP headers that Amazon CloudFront removes or adds in responses that it sends to viewers. For more information about response headers policies and reasons to use them, see Add or remove HTTP headers in CloudFront responses with a policy.

The following topics explain the settings in a response headers policy. The settings are grouped into categories, which are represented in the following topics.

Policy details (metadata)

The policy details settings contain metadata about a response headers policy.

Name – A name to identify the response headers policy. In the console, you use the name to attach the policy to a cache behavior.
Description (optional) – A comment to describe the response headers policy. This is optional, but it can help you identify the purpose of the policy.

CORS headers

The cross-origin resource sharing (CORS) settings allow you to add and configure CORS headers in a response headers policy.

This list focuses on how to specify settings and valid values in a response headers policy. For more information about each of these headers and how they're used for real-world CORS requests and responses, see cross-origin resource sharing in the MDN Web Docs and the CORS protocol spec.

Access-Control-Allow-Credentials

This is a Boolean setting (true or false) that determines if CloudFront adds the Access-Control-Allow-Credentials header in responses to CORS requests. When this setting is set to true, CloudFront adds the Access-Control-Allow-Credentials: true header in responses to CORS requests. Otherwise, CloudFront doesn't add this header to responses.

Access-Control-Allow-Headers

Specifies the header names that CloudFront uses as values for the Access-Control-Allow-Headers header in responses to CORS preflight requests. Valid values for this setting include HTTP header names or the wildcard character (*), which indicates that all headers are allowed.

Note

The Authorization header can't use a wildcard and must be listed explicitly.

Examples of valid use of the wildcard character
Example	Will match	Will not match
`x-amz-*`	`x-amz-test` `x-amz-`	`x-amz`
`x-*-amz`	`x-test-amz` `x--amz`
`*`	All headers except `Authorization`	`Authorization`

Access-Control-Allow-Methods

Specifies the HTTP methods that CloudFront uses as values for the Access-Control-Allow-Methods header in responses to CORS preflight requests. Valid values are GET, DELETE, HEAD, OPTIONS, PATCH, POST, PUT, and ALL. ALL is a special value that includes all of the listed HTTP methods.

Access-Control-Allow-Origin

Specifies the values that CloudFront can use in the Access-Control-Allow-Origin response header. Valid values for this setting include a specific origin (such as http://www.example.com) or the wildcard character (*), which indicates that all origins are allowed.

Notes

The wildcard character (*) is allowed as the leftmost subdomain (*.example.org).
The wildcard character (*) isn't allowed in the following positions:
- Top-level domains (example.*)
- To the right of subdomains (test.*.example.org) or within any subdomains (*test.example.org)
- Inside of terms (exa*mple.org)

For examples of ways to use the wildcard character, see the following table.

Example	Will match	Will not match
`http://*.example.org`	`http://www.example.org` `http://test.example.org`	`https://test.example.org` `https://test.example.org:123` `http://test.example.org:123`
`*.example.org`	`test.example.org` `test.test.example.org` `.example.org` `http://test.example.org` `https://test.example.org`	`http://test.example.org:123` `https://test.example.org:123`
`example.org`	`http://example.org` `https://example.org`
`http://example.org`		`https://example.org` `http://example.org:123`
`http://example.org:*`	`http://example.org:123` `http://example.org`
`http://example.org:1*3`	`http://example.org:123` `http://example.org:1893` `http://example.org:13`
`.example.org:1`	`test.example.org:123`

Access-Control-Expose-Headers

Specifies the header names that CloudFront uses as values for the Access-Control-Expose-Headers header in responses to CORS requests. Valid values for this setting include HTTP header names or the wildcard character (*).

Access-Control-Max-Age

A number of seconds, which CloudFront uses as the value for the Access-Control-Max-Age header in responses to CORS preflight requests.

Origin override

A Boolean setting that determines how CloudFront behaves when the response from the origin contains one of the CORS headers that's also in the policy.

When set to true and the origin response contains a CORS header that's also in the policy, CloudFront adds the CORS header in the policy to the response. CloudFront then sends that response to the viewer. CloudFront ignores the header that it received from the origin.
When set to false and the origin response contains a CORS header (regardless of whether the CORS header is in the policy), CloudFront includes the CORS header that it received from the origin to the response. CloudFront doesn't add any CORS headers in the policy to the response that is sent to the viewer.

Security headers

You can use the security headers settings to add and configure several security-related HTTP response headers in a response headers policy.

This list describes how you can specify settings and valid values in a response headers policy. For more information about each of these headers and how they're used in real-world HTTP responses, see the links to the MDN Web Docs.

Content-Security-Policy

Specifies the content security policy directives that CloudFront uses as values for the Content-Security-Policy response header.

For more information about this header and valid policy directives, see Content-Security-Policy in the MDN Web Docs.

Note

The Content-Security-Policy header value is limited to 1783 characters.

Referrer-Policy

Specifies the referrer policy directive that CloudFront uses as the value for the Referrer-Policy response header. Valid values for this setting are no-referrer, no-referrer-when-downgrade, origin, origin-when-cross-origin, same-origin, strict-origin, strict-origin-when-cross-origin, and unsafe-url.

For more information about this header and these directives, see Referrer-Policy in the MDN Web Docs.

Strict-Transport-Security

Specifies the directives and settings that CloudFront uses as the value for the Strict-Transport-Security response header. For this setting, you separately specify:

A number of seconds, which CloudFront uses as the value for the max-age directive of this header
A Boolean setting (true or false) for preload, which determines whether CloudFront includes the preload directive in the value of this header
A Boolean setting (true or false) for includeSubDomains, which determines whether CloudFront includes the includeSubDomains directive in the value of this header

For more information about this header and these directives, see Strict-Transport-Security in the MDN Web Docs.

X-Content-Type-Options

This is a Boolean setting (true or false) that determines if CloudFront adds the X-Content-Type-Options header to responses. When this setting is true, CloudFront adds the X-Content-Type-Options: nosniff header to responses. Otherwise CloudFront doesn't add this header.

For more information about this header, see X-Content-Type-Options in the MDN Web Docs.

X-Frame-Options

Specifies the directive that CloudFront uses as the value for the X-Frame-Options response header. Valid values for this setting are DENY or SAMEORIGIN.

For more information about this header and these directives, see X-Frame-Options in the MDN Web Docs.

X-XSS-Protection

Specifies the directives and settings that CloudFront uses as the value for the X-XSS-Protection response header. For this setting, you separately specify:

An X-XSS-Protection setting of 0 (disables XSS filtering) or 1 (enables XSS filtering)
A Boolean setting (true or false) for block, which determines whether CloudFront includes the mode=block directive in the value for this header
A reporting URI, which determines whether CloudFront includes the report=reporting URI directive in the value for this header

You can specify true for block, or you can specify a reporting URI, but you can't specify both together. For more information about this header and these directives, see X-XSS-Protection in the MDN Web Docs.

Origin override

Each of these security headers settings contains a Boolean setting (true or false) that determines how CloudFront behaves when the response from the origin contains that header.

When this setting is set to true and the origin response contains the header, CloudFront adds the header in the policy to the response that it sends to the viewer. It ignores the header that it received from the origin.

When this setting is set to false and the origin response contains the header, CloudFront includes the header that it received from the origin in the response that it sends to the viewer.

When the origin response doesn't contain the header, CloudFront adds the header in the policy to the response that it sends to the viewer. CloudFront does this when this setting is set to true or false.

Custom headers

You can use custom headers settings to add and configure custom HTTP headers in a response headers policy. CloudFront adds these headers to every response that it returns to viewers. For each custom header, you also specify the value for the header, though specifying a value is optional. This is because CloudFront can add a response header with no value.

Each custom header also has its own Origin override setting:

When this setting is set to true and the origin response contains the custom header that's in the policy, CloudFront adds the custom header in the policy to the response that it sends to the viewer. It ignores the header that it received from the origin.
When this setting is false and the origin response contains the custom header that's in the policy, CloudFront includes the custom header that it received from the origin in the response that it sends to the viewer.
When the origin response doesn't contain the custom header that's in the policy, CloudFront adds the custom header in the policy to the response that it sends to the viewer. CloudFront does this when this setting is set to true or false.

Remove headers

You can specify headers that you want CloudFront to remove from the responses it receives from the origin so the headers are not included in the responses that CloudFront sends to viewers. CloudFront removes the headers from every response it sends to viewers, whether the objects is served from CloudFront's cache or from the origin. For example, you can remove headers that are of no use to browsers, such as X-Powered-By or Vary, so that CloudFront removes these headers from the responses that it sends to viewers.

When you specify headers to remove using a response headers policy, CloudFront removes the headers first and then adds any headers that are specified in other sections of the response headers policy (CORS headers, security headers, custom headers, etc.). If you specify a header to remove but also add the same header in another section of the policy, CloudFront includes the header in the responses that it sends to viewers.

Note

You can use a response headers policy to remove the Server and Date headers that CloudFront received from the origin, so that these headers (as received from the origin) are not included in the responses that CloudFront sends to viewers. However, if you do that, CloudFront adds its own version of these headers to responses that it sends to viewers. For the Server header that CloudFront adds, the header's value is CloudFront.

Headers that you can't remove

You cannot remove the following headers using a response headers policy. If you specify these headers in the Remove headers section of a response headers policy (ResponseHeadersPolicyRemoveHeadersConfig in the API), you receive an error.

Connection
Content-Encoding
Content-Length
Expect
Host
Keep-Alive
Proxy-Authenticate
Proxy-Authorization
Proxy-Connection
Trailer
Transfer-Encoding
Upgrade
Via
Warning
X-Accel-Buffering
X-Accel-Charset
X-Accel-Limit-Rate
X-Accel-Redirect
X-Amz-Cf-.*
X-Amzn-Auth
X-Amzn-Cf-Billing
X-Amzn-Cf-Id
X-Amzn-Cf-Xff
X-Amzn-ErrorType
X-Amzn-Fle-Profile
X-Amzn-Header-Count
X-Amzn-Header-Order
X-Amzn-Lambda-Integration-Tag
X-Amzn-RequestId
X-Cache
X-Edge-.*
X-Forwarded-Proto
X-Real-Ip

Server-Timing header

Use the Server-Timing header setting to enable the Server-Timing header in HTTP responses sent from CloudFront. You can use this header to view metrics that can help you gain insights about the behavior and performance of CloudFront and your origin. For example, you can see which cache layer served a cache hit. Or, you can see the first byte latency from the origin if there's a cache miss. The metrics in the Server-Timing header can help you troubleshoot issues or test the efficiency of your CloudFront or origin configuration.

For more information about using the Server-Timing header with CloudFront, see the following topics.

To enable the Server-Timing header, create (or edit) a response headers policy.