CORS in Action: Creating and consuming cross-origin APIs (2015)

Appendix A. CORS reference

Clients and servers using CORS “talk” to each other through request and response headers. This appendix documents headers and other terms used when making CORS requests. It’s based on the latest version of the CORS spec at the time of writing (W3C Recommendation, January 16, 2014, which can be found at www.w3.org/TR/2014/REC-cors-20140116/).

A.1. HTTP headers

This section documents HTTP headers used by CORS. Headers can be categorized in different ways: they can either be present on the request from the browser, or on the response from the server; or they can be present on the preflight request, the actual request, or both (although it doesn’t hurt if preflight request headers are also on the actual request).

Request headers

The browser is responsible for setting the CORS request headers, and these headers can’t be overridden by the client code. Table A.1 documents the headers that may be present on CORS requests.

Table A.1. Request headers on all CORS requests

Header	Included on preflight request, actual request, or both?	Details
Origin	Both	The client’s origin. For example, for a request from http://www.example.com/sample/path, the Origin header value would be http://www.example.com. Required on all CORS requests (preflight and actual). Some browsers may add the Origin header on same-origin PUT, POST, and DELETE requests. The origin is defined in RFC6454 “The Web Origin Concept” (http://tools.ietf.org/html/rfc6454). This spec is separate from the CORS spec.
Access-Control-Request-Headers	Preflight	A comma-separated list of headers the client would like to send on the actual request. Used during a preflight request to ask the server’s permission to send certain request headers. Simple headers (defined in A.2.2) may not be included in this header.
Access-Control-Request-Method	Preflight	The HTTP method the client would like to use for the actual request. This header is required on all preflight requests, even if the value is a simple method (defined in A.2.1).

Response headers

The server is responsible for setting the CORS response headers. Using these response headers, the server can control how cross-origin requests behave. Table A.2 documents the headers that may be present on all CORS responses (preflight and actual responses).

Table A.1. Response headers on all CORS responses

Header	Included on preflight response, actual response, or both?	Details
Access-Control-Allow-Credentials	Both	The header has only one valid value: true. This header is optional. Its presence with true value indicates that the server allows user credentials such as cookies on cross-origin requests. If the client would like to include user credentials on cross-origin requests, they must also set the XML-Http-Request’s withCredentials property to true. If the server doesn’t allow user credentials on cross-origin requests, this header should be omitted.
Access-Control-Allow-Headers	Preflight	A comma-separated list of headers that the server allows on cross-origin requests. If a value is a simple header (defined in A.2.2), it doesn’t need to be included in this header. Adding headers in the list causes no harm.
Access-Control-Allow-Methods	Preflight	A comma-separated list of HTTP methods that the server allows on cross-origin requests. If the value is a simple method (defined in A.2.1), it doesn’t need to be included in this header.
Access-Control-Allow-Origin	Both	Gives permission to make a cross-origin request. Valid values include: , null, or the client’s actual origin value (for example, http://www.example.com*). Required on all CORS responses.
Access-Control-Expose-Headers	Actual	A comma-separated list of HTTP headers. Indicates which response headers a client can read from the server’s response. If a header is a simple response header (defined in A.2.3), it doesn’t need to be included in this list.
Access-Control-Max-Age	Preflight	The number of seconds the preflight request cache should store the preflight response. Browsers may cap this value. Chrome won’t cache preflight responses for more than 5 minutes, while Firefox won’t cache preflight responses for more than 24 hours.

A.2. Other terms used in CORS

In addition to the headers just noted, there are a few other important terms used by CORS.

Simple method

A simple method is an HTTP method that won’t trigger a preflight request. The simple methods are defined as:

· GET

· HEAD

· POST

Note that requests with a simple method may still trigger a preflight request if they contain nonsimple headers. The next section covers simple headers.

Simple header

A simple header is an HTTP request header that won’t trigger a preflight request. The client doesn’t need the server’s permission (via a preflight) to make requests with only these headers. The simple headers are defined as:

· Accept

· Accept-Language

· Content-Language

· Content-Type, but only if the value is one of the following:

o application/x-form-urlencoded

o multipart/form-data

o text/plain

Simple response header

During a same-origin request, the client JavaScript code can access the HTTP response headers using the getResponseHeader or getAllResponseHeaders methods on the XMLHttpRequest object. But cross-origin requests are limited in which response headers are visible to the client. Simple response headers are those that are visible to the client by default. All other headers need permission from the server to be viewed on the client; the server gives permission by using the Access-Control-Expose-Headers header. The simple response headers are defined as:

· Cache-Control

· Content-Language

· Content-Type

· Expires

· Last-Modified

· Pragma