Amazon CloudFront
Developer Guide (API Version 2014-10-21)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.

Request and Response Behavior for Custom Origins

How CloudFront Processes and Forwards Requests to Your Custom Origin Server

For information about how CloudFront processes viewer requests and forwards the requests to your custom origin, see the applicable topic:

Authentication

For GET and HEAD requests, do not configure your origin server to request client authentication. CloudFront removes the Authorization header before forwarding requests to your origin.

For OPTIONS requests, you can configure your origin server to request client authentication only if you use the following CloudFront settings:

  • Configure CloudFront to forward the Authorization header to your origin

  • Configure CloudFront to not cache the response to OPTIONS requests

For DELETE, PATCH, POST, and PUT requests, if you configure CloudFront to forward the Authorization header to your origin, you can configure your origin server to request client authentication.

You can configure CloudFront to forward requests to your origin using either HTTP or HTTPS; for more information, see How to Require HTTPS for Communication between Viewers, CloudFront, and Your Origin.

Caching Duration and Minimum TTL

For web distributions, to control how long your objects stay in a CloudFront cache before CloudFront forwards another request to your origin, you can:

  • Configure your origin to add a Cache-Control or an Expires header field to each object.

  • Specify a value for Minimum TTL in CloudFront cache behaviors.

  • Use the default value of 24 hours.

For more information, see Specifying How Long Objects Stay in a CloudFront Edge Cache (Expiration).

Client IP Addresses

CloudFront forwards the client IP address to your origin in the X-Forwarded-For request header. The X-Forwarded-For request header looks like this:

X-Forwarded-For: 192.0.2.235

If the X-Forwarded-For request header contains two or more IP addresses, the first one is always the client IP address. The other addresses are for each successive proxy that passes along the request; the last IP address is for the proxy that forwarded the request to CloudFront:

X-Forwarded-For: client-IP-address, proxy-IP-address, another-proxy-IP-address

Compression

CloudFront forwards requests that have the Accept-Encoding field values "identity" and "gzip". For more information, see Serving Compressed Files.

Conditional Requests

When CloudFront receives a request for an object that has expired from an edge cache, it forwards the request to the origin either to get the latest version of the object or to get confirmation from the origin that the CloudFront edge cache already has the latest version. Typically, when the origin last sent the object to CloudFront, it included an ETag value, a LastModified value, or both values in the response. In the new request that CloudFront forwards to the origin, CloudFront adds one or both of the following:

  • An If-Match or If-None-Match header that contains the ETag value for the expired version of the object.

  • An If-Modified-Since header that contains the LastModified value for the expired version of the object.

The origin uses this information to determine whether the object has been updated and, therefore, whether to return the entire object to CloudFront or to return only an HTTP 304 status code (not modified).

Cookies

You can configure CloudFront to forward cookies to your origin. For more information, see Configuring CloudFront to Cache Objects Based on Cookies.

Cross-Origin Resource Sharing (CORS)

If you want CloudFront to respect cross-origin resource sharing settings, configure CloudFront to forward the Origin header to your origin. For more information, see Configuring CloudFront to Cache Objects Based on Request Headers.

Encryption

CloudFront forwards HTTPS requests to the origin server using the SSLv3 or TLSv1 protocols and the following ciphers:

  • ECDHE-RSA-AES128-GCM-SHA256

  • ECDHE-RSA-AES128-SHA256

  • ECDHE-RSA-AES128-SHA

  • ECDHE-RSA-AES256-GCM-SHA384

  • ECDHE-RSA-AES256-SHA384

  • ECDHE-RSA-AES256-SHA

  • AES128-GCM-SHA256

  • AES256-GCM-SHA384

  • AES128-SHA256

  • AES256-SHA

  • AES128-SHA

  • RC4-MD5

If your origin server does not support at least one of these ciphers, CloudFront cannot establish an SSL connection to your origin.

When establishing an HTTPS connection to the origin, CloudFront adds a Server Name Indication (SNI) extension and includes the value of the applicable Origin Domain Name for your distribution. For more information about SNI, see Section 3.1 of RFC 4366, Transport Layer Security (TLS) Extensions.

HTTP Methods

If you configure CloudFront to process all of the HTTP methods that it supports, CloudFront accepts the following requests from viewers and forwards them to your custom origin:

  • DELETE

  • GET

  • HEAD

  • OPTIONS

  • PATCH

  • POST

  • PUT

CloudFront always caches responses to GET and HEAD requests. You can also configure CloudFront to cache responses to OPTIONS requests. CloudFront does not cache responses to requests that use the other methods.

For information about configuring whether your custom origin processes these methods, see the documentation for your origin.

Caution

If you configure CloudFront to accept and forward to your origin all of the HTTP methods that CloudFront supports, configure your origin server to handle all methods. For example, if you configure CloudFront to accept and forward these methods because you want to use POST, you must configure your origin server to handle DELETE requests appropriately so viewers can't delete resources that you don't want them to. For more information, see the documentation for your HTTP server.

HTTP Request Headers and CloudFront Behavior

The following table lists HTTP request headers and, for each header, explains the following:

  • CloudFront behavior if you don't configure CloudFront to forward the header to your origin, which causes CloudFront to cache your objects based on header values.

  • Whether you can configure CloudFront to cache objects based on header values for that header.

    You can configure CloudFront to cache objects based on values in the Date and User-Agent headers, but we don't recommend it. These headers have a lot of possible values, and caching based on their values would cause CloudFront to forward significantly more requests to your origin.

For more information about caching based on header values, see Configuring CloudFront to Cache Objects Based on Request Headers.

HeaderBehavior If You Don't Configure CloudFront to Cache Based on Header ValuesCaching Based on Header Values Is Supported

Customer-defined headers

CloudFront forwards the headers to your origin.

Yes

Accept

CloudFront removes the header.

Yes

Accept-Charset

CloudFront removes the header.

Yes

Accept-Encoding

If the value contains gzip, CloudFront forwards Accept-Encoding: gzip to your origin.

If the value does not contain gzip, CloudFront removes the Accept-Encoding header field before forwarding the request to your origin.

No

Accept-Language

CloudFront removes the header.

Yes

Authorization

  • GET and HEAD requests: CloudFront removes the Authorization header field before forwarding the request to your origin.

  • OPTIONS requests: CloudFront removes the Authorization header field before forwarding the request to your origin if you configure CloudFront to cache responses to OPTIONS requests.

    CloudFront forwards the Authorization header field to your origin if you do not configure CloudFront to cache responses to OPTIONS requests.

  • DELETE, PATCH, POST, and PUT requests: CloudFront does not remove the header field before forwarding the request to your origin.

Yes

Cache-Control

CloudFront forwards the header to your origin.

No

CloudFront-Forwarded-Proto

CloudFront does not add the header before forwarding the request to your origin.

For more information, see Configuring CloudFront to Cache Objects Based on the Protocol of the Request.

Yes

CloudFront-Is-Desktop-Viewer

CloudFront does not add the header before forwarding the request to your origin.

For more information, see Configuring CloudFront to Cache Objects Based on the Device Type.

Yes

CloudFront-Is-Mobile-Viewer

CloudFront does not add the header before forwarding the request to your origin.

For more information, see Configuring CloudFront to Cache Objects Based on the Device Type.

Yes

CloudFront-Is-Tablet-Viewer

CloudFront does not add the header before forwarding the request to your origin.

For more information, see Configuring CloudFront to Cache Objects Based on the Device Type.

Yes

CloudFront-Viewer-Country

CloudFront does not add the header before forwarding the request to your origin.

Yes

Connection

CloudFront replaces this header with Connection: Keep-Alive before forwarding the request to your origin.

No

Content-Length

CloudFront forwards the header to your origin.

No

Content-MD5

CloudFront forwards the header to your origin.

Yes

Content-Type

CloudFront forwards the header to your origin.

Yes

Cookie

If you configure CloudFront to forward cookies, it will forward the Cookie header field to your origin. If you don't, CloudFront removes the Cookie header field. For more information, see Configuring CloudFront to Cache Objects Based on Cookies.

No

Date

CloudFront forwards the header to your origin.

Yes, but not recommended

Expect

CloudFront removes the header.

Yes

From

CloudFront forwards the header to your origin.

Yes

Host

CloudFront sets the value to the domain name of the origin that is associated with the requested object.

Yes

If-Match

CloudFront forwards the header to your origin.

Yes

If-Modified-Since

CloudFront forwards the header to your origin.

Yes

If-None-Match

CloudFront forwards the header to your origin.

Yes

If-Range

CloudFront forwards the header to your origin.

Yes

If-Unmodified-Since

CloudFront forwards the header to your origin.

Yes

Max-Forwards

CloudFront forwards the header to your origin.

No

Origin

CloudFront forwards the header to your origin.

Yes

Pragma

CloudFront forwards the header to your origin.

No

Proxy-Authorization

CloudFront removes the header.

No

Proxy-Connection

CloudFront removes the header.

No

Range

CloudFront forwards the header to your origin. For more information, see How CloudFront Processes Partial Requests for an Object (Range GETs).

Yes, by default

Referer

CloudFront removes the header.

Yes

Request-Range

CloudFront forwards the header to your origin.

No

TE

CloudFront removes the header.

No

Trailer

CloudFront removes the header.

No

Transfer-Encoding

CloudFront forwards the header to your origin.

No

Upgrade

CloudFront removes the header.

No

User-Agent

CloudFront replaces the value of this header field with Amazon CloudFront. If you want CloudFront to cache your content based on the device the user is using, see Configuring CloudFront to Cache Objects Based on the Device Type.

Yes, but not recommended

Via

CloudFront forwards the header to your origin.

Yes

Warning

CloudFront forwards the header to your origin.

Yes

HTTP Version

CloudFront forwards requests to your custom origin using HTTP/1.1.

Maximum Length of a Request and Maximum Length of a URL

The maximum length of a request, including the path, the query string (if any), and headers, is 20480 bytes.

CloudFront constructs a URL from the request. The maximum length of this URL is 8192 bytes.

If a request or a URL exceeds these limits, CloudFront drops the request.

OCSP Stapling

When a viewer submits an HTTPS request for an object, either CloudFront or the viewer needs to confirm with the certificate authority (CA) that the SSL certificate for the domain has not been revoked. OCSP stapling speeds up certificate validation by allowing CloudFront to validate the certificate and to cache the response from the CA, so the client doesn't need to validate the certificate directly with the CA.

The performance improvement of OCSP stapling is more pronounced when CloudFront receives a lot of HTTPS requests for objects in the same domain. Each server in a CloudFront edge location must submit a separate validation request. When CloudFront receives a lot of HTTPS requests for the same domain, every server in the edge location soon has a response from the CA that it can "staple" to a packet in the SSL handshake; when the viewer is satisfied that the certificate is valid, CloudFront can serve the requested object. If your distribution doesn't get much traffic in a CloudFront edge location, new requests are more likely to be directed to a server that hasn't validated the certificate with the CA yet. In that case, the viewer separately performs the validation step and the CloudFront server serves the object. That CloudFront server also submits a validation request to the CA, so the next time it receives a request that includes the same domain name, it has a validation response from the CA.

Protocols

CloudFront forwards HTTP or HTTPS requests to the origin server based on the following:

  • The protocol of the request that the viewer sends to CloudFront, either HTTP or HTTPS.

  • The value of the Origin Protocol Policy field in the CloudFront console or, if you're using the CloudFront API, the OriginProtocolPolicy element in the DistributionConfig complex type. In the CloudFront console, the options are HTTP Only and Match Viewer.

If you specify HTTP Only, CloudFront forwards requests to the origin server using only the HTTP protocol, regardless of the protocol in the viewer request.

If you specify Match Viewer, CloudFront forwards requests to the origin server using the protocol in the viewer request. Note that CloudFront caches the object only once even if viewers make requests using both HTTP and HTTPS protocols.

Caution

If the viewer request uses the HTTPS protocol, and if the origin server returns an invalid certificate or a self-signed certificate, CloudFront drops the TCP connection.

For information about how to update a distribution using the CloudFront console, see Listing, Viewing, and Updating CloudFront Distributions. For information about how to update a distribution using the CloudFront API, go to PUT Distribution Config in the Amazon CloudFront API Reference.

Query Strings

You can configure whether CloudFront forwards query string parameters to your origin. For more information, see Configuring CloudFront to Cache Based on Query String Parameters.

Request Timeout

When CloudFront requests data from your origin, if the origin doesn't respond within 30 seconds or stops responding for 30 seconds, CloudFront drops the connection and makes two additional attempts to contact the origin. If the origin doesn't reply during the third attempt, CloudFront doesn't try again until it receives another request for content on the same origin.

User-Agent Header

If you want CloudFront to cache different versions of your objects based on the device a user is using to view your content, we recommend that you configure CloudFront to forward the applicable headers to your custom origin:

  • CloudFront-Is-Mobile-Viewer

  • CloudFront-Is-Tablet-Viewer

  • CloudFront-Is-Desktop-Viewer

Based on the value of the User-Agent header, CloudFront sets the value of these headers to true or false before forwarding the request to your origin. If a device falls into more than one category, more than one value might be true. For example, for some tablet devices, CloudFront might set both CloudFront-Is-Mobile-Viewer and CloudFront-Is-Tablet-Viewer to true. For more information about configuring CloudFront to cache based on request headers, see Configuring CloudFront to Cache Objects Based on Request Headers.

You can configure CloudFront to cache objects based on values in the User-Agent header, but we don't recommend it. The User-Agent header has a lot of possible values, and caching based on those values would cause CloudFront to forward significantly more requests to your origin.

If you do not configure CloudFront to cache objects based on values in the User-Agent header, CloudFront CloudFront adds a User-Agent header with the following value before it forwards a request to your origin:

User-Agent = Amazon CloudFront

CloudFront adds this header regardless of whether the request from the viewer included a User-Agent header. If the request from the viewer includes a User-Agent header, CloudFront removes it.

How CloudFront Processes Responses from Your Custom Origin Server

For information about how CloudFront processes responses from custom origin servers, see the applicable topic:

Caching

  • Ensure that the origin server sets valid and accurate values for the Date and Last-Modified header fields.

  • If requests from viewers include the If-Match or If-None-Match request header fields, set the ETag response header field. If you do not specify an ETag value, CloudFront ignores subsequent If-Match or If-None-Match headers.

Canceled Requests

If an object is not in the edge cache, and if a viewer terminates a session (for example, closes a browser) after CloudFront gets the object from your origin but before it can deliver the requested object, CloudFront does not cache the object in the edge location.

Content Negotiation

The only acceptable value for the Vary header is Accept-Encoding. CloudFront ignores other values.

Cookies

If you enable cookies for a cache behavior, and if the origin returns cookies with an object, CloudFront caches both the object and the cookies. Note that this reduces cacheability for an object. For more information, see Configuring CloudFront to Cache Objects Based on Cookies.

Dropped TCP Connections

If the TCP connection between CloudFront and your origin drops while your origin is returning an object to CloudFront, CloudFront behavior depends on whether your origin included a Content-Length header in the response:

  • Content-Length header: CloudFront returns the object to the viewer as it gets the object from your origin. However, if the value of the Content-Length header doesn't match the size of the object, CloudFront doesn't cache the object.

  • Transfer-Encoding: Chunked: CloudFront returns the object to the viewer as it gets the object from your origin. However, if the chunked response is not complete, CloudFront does not cache the object.

  • No Content-Length header: CloudFront returns the object to the viewer and caches it, but the object may not be complete. Without a Content-Length header, CloudFront cannot determine whether the TCP connection was dropped accidentally or on purpose.

We recommend that you configure your HTTP server to add a Content-Length header to prevent CloudFront from caching partial objects.

HTTP Response Headers that CloudFront Removes or Updates

CloudFront removes or updates the following header fields before forwarding the response from your origin to the viewer:

  • Set-Cookie: If you configure CloudFront to forward cookies, it will forward the Set-Cookie header field to clients. For more information, see Configuring CloudFront to Cache Objects Based on Cookies.

  • Trailer

  • Transfer-Encoding: If your origin returns this header field, CloudFront sets the value to chunked before returning the response to the viewer.

  • Upgrade

  • Vary

  • Via: Regardless of whether your origin returns this header field to CloudFront, CloudFront sets the value to:

    Via: 1.1 alphanumeric-string.cloudfront.net (CloudFront)

    before returning the response to the viewer. For example:

    Via: 1.1 1026589cc7887e7a0dc7827b4example.cloudfront.net (CloudFront)

Maximum File Size

The maximum size of a response body that CloudFront will return to the viewer is 20 GB. This includes chunked transfer responses that don't specify the Content-Length header value.

Origin Unavailable

If your origin server is unavailable and CloudFront gets a request for an object that is in the edge cache but that has expired (for example, because the period of time specified in the Cache-Control max-age directive has passed), CloudFront either serves the expired version of the object or serves a custom error page. For more information, see How CloudFront Processes and Caches HTTP 4xx and 5xx Status Codes.

In some cases, an object that is seldom requested is evicted and is no longer available in the edge cache. CloudFront can't serve an object that has been evicted.

Redirects

If you change the location of an object on the origin server, you can configure your web server to redirect requests to the new location. After you configure the redirect, the first time a viewer submits a request for the object, CloudFront Front sends the request to the origin, and the origin responds with a redirect (for example, 302 Moved Temporarily). CloudFront caches the redirect and returns it to the viewer. CloudFront does not follow the redirect.

You can configure your web server to redirect requests to one of the following locations:

  • The new URL of the object on the origin server. When the viewer follows the redirect to the new URL, the viewer bypasses CloudFront and goes straight to the origin. As a result, we recommend that you not redirect requests to the new URL of the object on the origin.

  • The new CloudFront URL for the object. When the viewer submits the request that contains the new CloudFront URL, CloudFront gets the object from the new location on your origin, caches it at the edge location, and returns the object to the viewer. Subsequent requests for the object will be served by the edge location. This avoids the latency and load associated with viewers requesting the object from the origin. However, every new request for the object will incur charges for two requests to CloudFront.

Transfer Encoding

CloudFront supports only the chunked value of the Transfer-Encoding header. If your origin returns Transfer-Encoding: chunked, CloudFront CloudFront returns the object to the client as the object is received at the edge location, and caches the object in chunked format for subsequent requests.

We recommend that you use chunked encoding if the content length of your response cannot be predetermined. For more information, see Dropped TCP Connections.