Cross-Origin Resource Sharing (CORS)

Thiscross-origin sharing standardcan enable cross-origin HTTP requests for:

• Invocations offetch()orXMLHttpRequest,as discussed above.
• Web Fonts (for cross-domain font usage in@font-facewithin CSS),so that servers can deploy TrueType fonts that can only be loaded cross-origin and used by websites that are permitted to do so.
• WebGL textures.
• Images/video frames drawn to a canvas usingdrawImage().
• CSS Shapes from images.

This is a general article about Cross-Origin Resource Sharing and includes a discussion of the necessary HTTP headers.

The Cross-Origin Resource Sharing standard works by adding newHTTP headersthat let servers describe which origins are permitted to read that information from a web browser. Additionally, for HTTP request methods that can cause side-effects on server data (in particular, HTTP methods other thanGET,orPOSTwith certainMIME types), the specification mandates that browsers "preflight" the request, soliciting supported methods from the server with the HTTPOPTIONSrequest method, and then, upon "approval" from the server, sending the actual request. Servers can also inform clients whether "credentials" (such asCookiesandHTTP Authentication) should be sent with requests.

CORS failures result in errors but for security reasons, specifics about the errorare not available to JavaScript.All the code knows is that an error occurred. The only way to determine what specifically went wrong is to look at the browser's console for details.

Subsequent sections discuss scenarios, as well as provide a breakdown of the HTTP headers used.

We present three scenarios that demonstrate how Cross-Origin Resource Sharing works. All these examples usefetch(),which can make cross-origin requests in any supporting browser.

Some requests don't trigger aCORS preflight.Those are calledsimple requestsfrom the obsoleteCORS spec,though theFetch spec(which now defines CORS) doesn't use that term.

The motivation is that the<form>element from HTML 4.0 (which predates cross-sitefetch()andXMLHttpRequest) can submit simple requests to any origin, so anyone writing a server must already be protecting againstcross-site request forgery(CSRF). Under this assumption, the server doesn't have to opt-in (by responding to a preflight request) to receive any request that looks like a form submission, since the threat of CSRF is no worse than that of form submission. However, the server still must opt-in usingAccess-Control-Allow-Origintosharethe response with the script.

Asimple requestis one thatmeets all the following conditions:

• One of the allowed methods:
  • GET
  • HEAD
  • POST
• Apart from the headers automatically set by the user agent (for example,Connection,User-Agent,orthe other headers defined in the Fetch spec as aforbidden header name), the only headers which are allowed to be manually set arethose which the Fetch spec defines as a CORS-safelisted request-header,which are:
  • Accept
  • Accept-Language
  • Content-Language
  • Content-Type(please note the additional requirements below)
  • Range(only with asimple range header value;e.g.,bytes=256-orbytes=127-255)
• The only type/subtype combinations allowed for themedia typespecified in theContent-Typeheader are:
  • application/x-www-form-urlencoded
  • multipart/form-data
  • text/plain
• If the request is made using anXMLHttpRequestobject, no event listeners are registered on the object returned by theXMLHttpRequest.uploadproperty used in the request; that is, given anXMLHttpRequestinstancexhr,no code has calledxhr.upload.addEventListener()to add an event listener to monitor the upload.
• NoReadableStreamobject is used in the request.

For example, suppose web content athttps://foo.examplewishes to fetch JSON content from domainhttps://bar.other.Code of this sort might be used in JavaScript deployed onfoo.example:

constfetchPromise=fetch("https://bar.other");

fetchPromise
.then((response)=>response.json())
.then((data)=>{
console.log(data);
});

This operation performs a simple exchange between the client and the server, using CORS headers to handle the privileges:

Let's look at what the browser will send to the server in this case:

GET/resources/public-data/HTTP/1.1
Host:bar.other
User-Agent:Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:71.0) Gecko/20100101 Firefox/71.0
Accept:text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language:en-us,en;q=0.5
Accept-Encoding:gzip,deflate
Connection:keep-alive
Origin:https://foo.example

The request header of note isOrigin,which shows that the invocation is coming fromhttps://foo.example.

Now let's see how the server responds:

HTTP/1.1200OK
Date:Mon, 01 Dec 2008 00:23:53 GMT
Server:Apache/2
Access-Control-Allow-Origin:*
Keep-Alive:timeout=2, max=100
Connection:Keep-Alive
Transfer-Encoding:chunked
Content-Type:application/xml

[…XML Data…]

In response, the server returns aAccess-Control-Allow-Originheader withAccess-Control-Allow-Origin: *,which means that the resource can be accessed byanyorigin.

Access-Control-Allow-Origin:*

This pattern of theOriginandAccess-Control-Allow-Originheaders is the simplest use of the access control protocol. If the resource owners athttps://bar.otherwished to restrict access to the resource to requestsonlyfromhttps://foo.example(i.e., no domain other thanhttps://foo.examplecan access the resource in a cross-origin manner), they would send:

Access-Control-Allow-Origin:https://foo.example

Unlikesimple requests,for "preflighted" requests the browser first sends an HTTP request using theOPTIONSmethod to the resource on the other origin, in order to determine if the actual request is safe to send. Such cross-origin requests are preflighted since they may have implications for user data.

The following is an example of a request that will be preflighted:

constfetchPromise=fetch("https://bar.other/doc",{
method:"POST",
mode:"cors",
headers:{
"Content-Type":"text/xml",
"X-PINGOTHER":"pingpong",
},
body:"<person><name>Arun</name></person>",
});

fetchPromise.then((response)=>{
console.log(response.status);
});

The example above creates an XML body to send with thePOSTrequest. Also, a non-standard HTTPX-PINGOTHERrequest header is set. Such headers are not part of HTTP/1.1, but are generally useful to web applications. Since the request uses aContent-Typeoftext/xml,and since a custom header is set, this request is preflighted.

Let's look at the full exchange between client and server. The first exchange is thepreflight request/response:

OPTIONS/docHTTP/1.1
Host:bar.other
User-Agent:Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:71.0) Gecko/20100101 Firefox/71.0
Accept:text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language:en-us,en;q=0.5
Accept-Encoding:gzip,deflate
Connection:keep-alive
Origin:https://foo.example
Access-Control-Request-Method:POST
Access-Control-Request-Headers:content-type,x-pingother

HTTP/1.1204No Content
Date:Mon, 01 Dec 2008 01:15:39 GMT
Server:Apache/2
Access-Control-Allow-Origin:https://foo.example
Access-Control-Allow-Methods:POST, GET, OPTIONS
Access-Control-Allow-Headers:X-PINGOTHER, Content-Type
Access-Control-Max-Age:86400
Vary:Accept-Encoding, Origin
Keep-Alive:timeout=2, max=100
Connection:Keep-Alive

The first block above represents the preflight request with theOPTIONSmethod. The browser determines that it needs to send this based on the request parameters that the JavaScript code snippet above was using, so that the server can respond whether it is acceptable to send the request with the actual request parameters. OPTIONS is an HTTP/1.1 method that is used to determine further information from servers, and is asafemethod, meaning that it can't be used to change the resource. Note that along with the OPTIONS request, two other request headers are sent:

Access-Control-Request-Method:POST
Access-Control-Request-Headers:content-type,x-pingother

TheAccess-Control-Request-Methodheader notifies the server as part of a preflight request that when the actual request is sent, it will do so with aPOSTrequest method. TheAccess-Control-Request-Headersheader notifies the server that when the actual request is sent, it will do so withX-PINGOTHERandContent-Typecustom headers. Now the server has an opportunity to determine whether it can accept a request under these conditions.

The second block above is the response that the server returns, which indicate that the request method (POST) and request headers (X-PINGOTHER) are acceptable. Let's have a closer look at the following lines:

Access-Control-Allow-Origin:https://foo.example
Access-Control-Allow-Methods:POST, GET, OPTIONS
Access-Control-Allow-Headers:X-PINGOTHER, Content-Type
Access-Control-Max-Age:86400

The server responds withAccess-Control-Allow-Origin: https://foo.example,restricting access to the requesting origin domain only. It also responds withAccess-Control-Allow-Methods,which says thatPOSTandGETare valid methods to query the resource in question (this header is similar to theAllowresponse header, but used strictly within the context of access control).

The server also sendsAccess-Control-Allow-Headerswith a value of "X-PINGOTHER, Content-Type",confirming that these are permitted headers to be used with the actual request. LikeAccess-Control-Allow-Methods,Access-Control-Allow-Headersis a comma-separated list of acceptable headers.

Finally,Access-Control-Max-Agegives the value in seconds for how long the response to the preflight request can be cached without sending another preflight request. The default value is 5 seconds. In the present case, the max age is 86400 seconds (= 24 hours). Note that each browser has amaximum internal valuethat takes precedence when theAccess-Control-Max-Ageexceeds it.

Once the preflight request is complete, the real request is sent:

POST/docHTTP/1.1
Host:bar.other
User-Agent:Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:71.0) Gecko/20100101 Firefox/71.0
Accept:text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language:en-us,en;q=0.5
Accept-Encoding:gzip,deflate
Connection:keep-alive
X-PINGOTHER:pingpong
Content-Type:text/xml; charset=UTF-8
Referer:https://foo.example/examples/preflightInvocation.html
Content-Length:55
Origin:https://foo.example
Pragma:no-cache
Cache-Control:no-cache

<person><name>Arun</name></person>

HTTP/1.1200OK
Date:Mon, 01 Dec 2008 01:15:40 GMT
Server:Apache/2
Access-Control-Allow-Origin:https://foo.example
Vary:Accept-Encoding, Origin
Content-Encoding:gzip
Content-Length:235
Keep-Alive:timeout=2, max=99
Connection:Keep-Alive
Content-Type:text/plain

[Some XML payload]

Preflighted requests and redirects

Not all browsers currently support following redirects after a preflighted request. If a redirect occurs after such a request, some browsers currently will report an error message such as the following:

The request was redirected tohttps://example.com/foo,which is disallowed for cross-origin requests that require preflight. Request requires preflight, which is disallowed to follow cross-origin redirects.

The CORS protocol originally required that behavior butwas subsequently changed to no longer require it.However, not all browsers have implemented the change, and thus still exhibit the originally required behavior.

Until browsers catch up with the spec, you may be able to work around this limitation by doing one or both of the following:

• Change the server-side behavior to avoid the preflight and/or to avoid the redirect
• Change the request such that it is asimple requestthat doesn't cause a preflight

If that's not possible, then another way is to:

1. Make asimple request(usingResponse.urlfor the Fetch API, orXMLHttpRequest.responseURL) to determine what URL the real preflighted request would end up at.
2. Make another request (therealrequest) using the URL you obtained fromResponse.urlorXMLHttpRequest.responseURLin the first step.

However, if the request is one that triggers a preflight due to the presence of theAuthorizationheader in the request, you won't be able to work around the limitation using the steps above. And you won't be able to work around it at all unless you have control over the server the request is being made to.

The most interesting capability exposed by bothfetch()orXMLHttpRequestand CORS is the ability to make "credentialed" requests that are aware ofHTTP cookiesand HTTP Authentication information. By default, in cross-originfetch()orXMLHttpRequestcalls, browsers willnotsend credentials.

To ask for afetch()request to include credentials, set thecredentialsoption to"include".

To ask for anXMLHttpRequestrequest to include credentials, set theXMLHttpRequest.withCredentialsproperty totrue.

In this example, content originally loaded fromhttps://foo.examplemakes a simple GET request to a resource onhttps://bar.otherwhich sets Cookies. Content on foo.example might contain JavaScript like this:

consturl="https://bar.other/resources/credentialed-content/";

constrequest=newRequest(url,{credentials:"include"});

constfetchPromise=fetch(request);
fetchPromise.then((response)=>console.log(response));

This code creates aRequestobject, setting thecredentialsoption to"include"in the constructor, then passes this request intofetch().Since this is a simpleGETrequest, it is not preflighted but the browser willrejectany response that does not have theAccess-Control-Allow-Credentials:trueheader, andnotmake the response available to the invoking web content.

Here is a sample exchange between client and server:

GET/resources/credentialed-content/HTTP/1.1
Host:bar.other
User-Agent:Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:71.0) Gecko/20100101 Firefox/71.0
Accept:text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language:en-us,en;q=0.5
Accept-Encoding:gzip,deflate
Connection:keep-alive
Referer:https://foo.example/examples/credential.html
Origin:https://foo.example
Cookie:pageAccess=2

HTTP/1.1200OK
Date:Mon, 01 Dec 2008 01:34:52 GMT
Server:Apache/2
Access-Control-Allow-Origin:https://foo.example
Access-Control-Allow-Credentials:true
Cache-Control:no-cache
Pragma:no-cache
Set-Cookie:pageAccess=3; expires=Wed, 31-Dec-2008 01:34:53 GMT
Vary:Accept-Encoding, Origin
Content-Encoding:gzip
Content-Length:106
Keep-Alive:timeout=2, max=100
Connection:Keep-Alive
Content-Type:text/plain

[text/plain payload]

Although the request'sCookieheader contains the cookie destined for the content onhttps://bar.other,if bar.other did not respond with anAccess-Control-Allow-Credentialswith valuetrue,as demonstrated in this example, the response would be ignored and not made available to the web content.

Preflight requests and credentials

CORS-preflight requests must never include credentials. Theresponseto a preflight request must specifyAccess-Control-Allow-Credentials: trueto indicate that the actual request can be made with credentials.

Credentialed requests and wildcards

When responding to a credentialed request:

• The servermust notspecify the "*"wildcard for theAccess-Control-Allow-Originresponse-header value, but must instead specify an explicit origin; for example:Access-Control-Allow-Origin: https://example.com
• The servermust notspecify the "*"wildcard for theAccess-Control-Allow-Headersresponse-header value, but must instead specify an explicit list of header names; for example,Access-Control-Allow-Headers: X-PINGOTHER, Content-Type
• The servermust notspecify the "*"wildcard for theAccess-Control-Allow-Methodsresponse-header value, but must instead specify an explicit list of method names; for example,Access-Control-Allow-Methods: POST, GET
• The servermust notspecify the "*"wildcard for theAccess-Control-Expose-Headersresponse-header value, but must instead specify an explicit list of header names; for example,Access-Control-Expose-Headers: Content-Encoding, Kuma-Revision

If a request includes a credential (most commonly aCookieheader) and the response includes anAccess-Control-Allow-Origin: *header (that is, with the wildcard), the browser will block access to the response, and report a CORS error in the devtools console.

But if a request does include a credential (like theCookieheader) and the response includes an actual origin rather than the wildcard (like, for example,Access-Control-Allow-Origin: https://example.com), then the browser will allow access to the response from the specified origin.

Also note that anySet-Cookieresponse header in a response would not set a cookie if theAccess-Control-Allow-Originvalue in that response is the "*"wildcard rather an actual origin.

Third-party cookies

Note that cookies set in CORS responses are subject to normal third-party cookie policies. In the example above, the page is loaded fromfoo.examplebut theCookieheader in the response is sent bybar.other,and would thus not be saved if the user's browser is configured to reject all third-party cookies.

Cookie in the request may also be suppressed in normal third-party cookie policies. The enforced cookie policy may therefore nullify the capability described in this chapter, effectively preventing you from making credentialed requests whatsoever.

Cookie policy around theSameSiteattribute would apply.

This section lists the HTTP response headers that servers return for access control requests as defined by the Cross-Origin Resource Sharing specification. The previous section gives an overview of these in action.

A returned resource may have oneAccess-Control-Allow-Originheader with the following syntax:

Access-Control-Allow-Origin:<origin> | *

Access-Control-Allow-Originspecifies either a single origin which tells browsers to allow that origin to access the resource; or else — for requestswithoutcredentials — the "*"wildcard tells browsers to allow any origin to access the resource.

For example, to allow code from the originhttps://mozilla.orgto access the resource, you can specify:

Access-Control-Allow-Origin:https://mozilla.org
Vary:Origin

If the server specifies a single origin (that may dynamically change based on the requesting origin as part of an allowlist) rather than the "*"wildcard, then the server should also includeOriginin theVaryresponse header to indicate to clients that server responses will differ based on the value of theOriginrequest header.

TheAccess-Control-Expose-Headersheader adds the specified headers to the allowlist that JavaScript (such asResponse.headers) in browsers is allowed to access.

Access-Control-Expose-Headers:<header-name>[, <header-name>]*

For example, the following:

Access-Control-Expose-Headers:X-My-Custom-Header, X-Another-Custom-Header

…would allow theX-My-Custom-HeaderandX-Another-Custom-Headerheaders to be exposed to the browser.

TheAccess-Control-Max-Ageheader indicates how long the results of a preflight request can be cached. For an example of a preflight request, see the above examples.

Access-Control-Max-Age:<delta-seconds>

Thedelta-secondsparameter indicates the number of seconds the results can be cached.

TheAccess-Control-Allow-Credentialsheader indicates whether or not the response to the request can be exposed when thecredentialsflag is true. When used as part of a response to a preflight request, this indicates whether or not the actual request can be made using credentials. Note that simpleGETrequests are not preflighted, and so if a request is made for a resource with credentials, if this header is not returned with the resource, the response is ignored by the browser and not returned to web content.

Access-Control-Allow-Credentials:true

Credentialed requestsare discussed above.

TheAccess-Control-Allow-Methodsheader specifies the method or methods allowed when accessing the resource. This is used in response to a preflight request. The conditions under which a request is preflighted are discussed above.

Access-Control-Allow-Methods:<method>[, <method>]*

An example of apreflight requestis given above, including an example which sends this header to the browser.

TheAccess-Control-Allow-Headersheader is used in response to apreflight requestto indicate which HTTP headers can be used when making the actual request. This header is the server side response to the browser'sAccess-Control-Request-Headersheader.

Access-Control-Allow-Headers:<header-name>[, <header-name>]*

This section lists headers that clients may use when issuing HTTP requests in order to make use of the cross-origin sharing feature. Note that these headers are set for you when making invocations to servers. Developers making cross-origin requests do not have to set any cross-origin sharing request headers programmatically.

TheOriginheader indicates the origin of the cross-origin access request or preflight request.

Origin:<origin>

The origin is a URL indicating the server from which the request is initiated. It does not include any path information, only the server name.

Note that in any access control request, theOriginheader isalwayssent.

TheAccess-Control-Request-Methodis used when issuing a preflight request to let the server know what HTTP method will be used when the actual request is made.

Access-Control-Request-Method:<method>

Examples of this usage can befound above.

TheAccess-Control-Request-Headersheader is used when issuing a preflight request to let the server know what HTTP headers will be used when the actual request is made (for example, by passing them as theheadersoption). This browser-side header will be answered by the complementary server-side header ofAccess-Control-Allow-Headers.

Access-Control-Request-Headers:<field-name>[,<field-name>]*

Examples of this usage can befound above.

• CORS errors
• Enable CORS: I want to add CORS support to my server
• Fetch API
• XMLHttpRequest
• Will it CORS?- an interactive CORS explainer & generator
• How to run Chrome browser without CORS
• Using CORS with All (Modern) Browsers
• Stack Overflow answer with "how to" info for dealing with common problems:
  • How to avoid the CORS preflight
  • How to use a CORS proxy to get around"No Access-Control-Allow-Origin header"
  • How to fix"Access-Control-Allow-Origin header must not be the wildcard"