diff options
Diffstat (limited to 'files/nl/web/http/cors/index.html')
| -rw-r--r-- | files/nl/web/http/cors/index.html | 567 |
1 files changed, 0 insertions, 567 deletions
diff --git a/files/nl/web/http/cors/index.html b/files/nl/web/http/cors/index.html deleted file mode 100644 index 463a0011bf..0000000000 --- a/files/nl/web/http/cors/index.html +++ /dev/null @@ -1,567 +0,0 @@ ---- -title: Cross-Origin Resource Sharing (CORS) -slug: Web/HTTP/CORS -tags: - - AJAX - - CORS - - Cross-Origin Resource Sharing - - Fetch - - Fetch API - - HTTP - - HTTP Access Controls - - NeedsTranslation - - Same-origin policy - - Security - - TopicStub - - XMLHttpRequest - - 'l10n:priority' -translation_of: Web/HTTP/CORS ---- -<div>{{HTTPSidebar}}</div> - -<p><span class="seoSummary">Cross-Origin Resource Sharing ({{Glossary("CORS")}}) is a mechanism that uses additional {{Glossary("HTTP")}} headers to tell a browser to let a web application running at one origin (domain) have permission to access selected resources from a server at a different origin.</span> A web application executes a <strong>cross-origin HTTP request</strong> when it requests a resource that has a different origin (domain, protocol, and port) than its own origin.</p> - -<p>An example of a cross-origin request: The frontend JavaScript code for a web application served from <code>http://domain-a.com</code> uses {{domxref("XMLHttpRequest")}} to make a request for <code>http://api.domain-b.com/data.json</code>.</p> - -<p>For security reasons, browsers restrict cross-origin HTTP requests initiated from within scripts. For example, <code>XMLHttpRequest</code> and the <a href="/en-US/docs/Web/API/Fetch_API">Fetch API</a> follow the <a href="/en-US/docs/Web/Security/Same-origin_policy">same-origin policy</a>. This means that a web application using those APIs can only request HTTP resources from the same origin the application was loaded from, unless the response from the other origin includes the right CORS headers.</p> - -<p><img alt="" src="https://mdn.mozillademos.org/files/14295/CORS_principle.png" style="height: 643px; width: 925px;"></p> - -<p>The CORS mechanism supports secure cross-origin requests and data transfers between browsers and web servers. Modern browsers use CORS in an API container such as <code>XMLHttpRequest</code> or <a href="/en-US/docs/Web/API/Fetch_API">Fetch</a> to help mitigate the risks of cross-origin HTTP requests.</p> - -<h2 id="Who_should_read_this_article">Who should read this article?</h2> - -<p>Everyone, really.</p> - -<p>More specifically, this article is for web administrators, server developers, and front-end developers. Modern browsers handle the client-side components of cross-origin sharing, including headers and policy enforcement. But this new standard means servers have to handle new request and response headers. Another article for server developers discussing <a href="/en-US/docs/Web/HTTP/Server-Side_Access_Control">cross-origin sharing from a server perspective (with PHP code snippets)</a> is supplementary reading.</p> - -<h2 id="What_requests_use_CORS">What requests use CORS?</h2> - -<p>This <a class="external" href="https://fetch.spec.whatwg.org/#http-cors-protocol">cross-origin sharing standard</a> is used to enable cross-site HTTP requests for:</p> - -<ul> - <li>Invocations of the {{domxref("XMLHttpRequest")}} or <a href="/en-US/docs/Web/API/Fetch_API">Fetch</a> APIs in a cross-site manner, as discussed above.</li> - <li>Web Fonts (for cross-domain font usage in <code>@font-face</code> within CSS), <a class="external" href="https://www.w3.org/TR/css-fonts-3/#font-fetching-requirements">so that servers can deploy TrueType fonts that can only be cross-site loaded and used by web sites that are permitted to do so.</a></li> - <li><a href="/en-US/docs/Web/API/WebGL_API/Tutorial/Using_textures_in_WebGL">WebGL textures</a>.</li> - <li>Images/video frames drawn to a canvas using {{domxref("CanvasRenderingContext2D.drawImage()", "drawImage()")}}.</li> -</ul> - -<p>This article is a general discussion of Cross-Origin Resource Sharing and includes a discussion of the necessary HTTP headers.</p> - -<h2 id="Functional_overview">Functional overview</h2> - -<p>The Cross-Origin Resource Sharing standard works by adding new <a href="/en-US/docs/Web/HTTP/Headers">HTTP headers</a> that allow servers to describe the set of origins that are permitted to read that information using a web browser. Additionally, for HTTP request methods that can cause side-effects on server's data (in particular, for HTTP methods other than {{HTTPMethod("GET")}}, or for {{HTTPMethod("POST")}} usage with certain <a href="/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types">MIME types</a>), the specification mandates that browsers "preflight" the request, soliciting supported methods from the server with an HTTP {{HTTPMethod("OPTIONS")}} request method, and then, upon "approval" from the server, sending the actual request with the actual HTTP request method. Servers can also notify clients whether "credentials" (including <a href="/en-US/docs/Web/HTTP/Cookies">Cookies</a> and HTTP Authentication data) should be sent with requests.</p> - -<p>CORS failures result in errors, but for security reasons, specifics about what went wrong <em>are not available to JavaScript code</em>. 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.</p> - -<p>Subsequent sections discuss scenarios, as well as provide a breakdown of the HTTP headers used.</p> - -<h2 id="Examples_of_access_control_scenarios">Examples of access control scenarios</h2> - -<p>Here, we present three scenarios that illustrate how Cross-Origin Resource Sharing works. All of these examples use the {{domxref("XMLHttpRequest")}} object, which can be used to make cross-site invocations in any supporting browser.</p> - -<p>The JavaScript snippets included in these sections (and running instances of the server-code that correctly handles these cross-site requests) can be found "in action" at <a class="external" href="http://arunranga.com/examples/access-control/">http://arunranga.com/examples/access-control/</a>, and will work in browsers that support cross-site <code>XMLHttpRequest</code>.</p> - -<p>A discussion of Cross-Origin Resource Sharing from a server perspective (including PHP code snippets) can be found in the <a class="internal" href="/en-US/docs/Web/HTTP/Server-Side_Access_Control">Server-Side Access Control (CORS)</a> article.</p> - -<h3 id="Simple_requests">Simple requests</h3> - -<p>Some requests don’t trigger a <a href="#Preflighted_requests">CORS preflight</a>. Those are called “simple requests” in this article, though the {{SpecName('Fetch')}} spec (which defines CORS) doesn’t use that term. A request that doesn’t trigger a <a href="#Preflighted_requests">CORS preflight</a>—a so-called “simple request” — is one that <strong>meets all the following conditions</strong>:</p> - -<ul> - <li>The only allowed methods are: - <ul> - <li>{{HTTPMethod("GET")}}</li> - <li>{{HTTPMethod("HEAD")}}</li> - <li>{{HTTPMethod("POST")}}</li> - </ul> - </li> - <li>Apart from the headers set automatically by the user agent (for example, {{HTTPHeader("Connection")}}, {{HTTPHeader("User-Agent")}}, or <a href="https://fetch.spec.whatwg.org/#forbidden-header-name">any of the other headers with names defined in the Fetch spec as a “forbidden header name”</a>), the only headers which are allowed to be manually set are <a href="https://fetch.spec.whatwg.org/#cors-safelisted-request-header">those which the Fetch spec defines as being a “CORS-safelisted request-header”</a>, which are: - <ul> - <li>{{HTTPHeader("Accept")}}</li> - <li>{{HTTPHeader("Accept-Language")}}</li> - <li>{{HTTPHeader("Content-Language")}}</li> - <li>{{HTTPHeader("Content-Type")}} (but note the additional requirements below)</li> - <li><code><a href="http://httpwg.org/http-extensions/client-hints.html#dpr">DPR</a></code></li> - <li>{{HTTPHeader("Downlink")}}</li> - <li><code><a href="http://httpwg.org/http-extensions/client-hints.html#save-data">Save-Data</a></code></li> - <li><code><a href="http://httpwg.org/http-extensions/client-hints.html#viewport-width">Viewport-Width</a></code></li> - <li><code><a href="http://httpwg.org/http-extensions/client-hints.html#width">Width</a></code></li> - </ul> - </li> - <li>The only allowed values for the {{HTTPHeader("Content-Type")}} header are: - <ul> - <li><code>application/x-www-form-urlencoded</code></li> - <li><code>multipart/form-data</code></li> - <li><code>text/plain</code></li> - </ul> - </li> - <li>No event listeners are registered on any {{domxref("XMLHttpRequestUpload")}} object used in the request; these are accessed using the {{domxref("XMLHttpRequest.upload")}} property.</li> - <li>No {{domxref("ReadableStream")}} object is used in the request.</li> -</ul> - -<div class="note"><strong>Note:</strong> These are the same kinds of cross-site requests that web content can already issue, and no response data is released to the requester unless the server sends an appropriate header. Therefore, sites that prevent cross-site request forgery have nothing new to fear from HTTP access control.</div> - -<div class="note"><strong>Note:</strong> WebKit Nightly and Safari Technology Preview place additional restrictions on the values allowed in the {{HTTPHeader("Accept")}}, {{HTTPHeader("Accept-Language")}}, and {{HTTPHeader("Content-Language")}} headers. If any of those headers have ”non-standard” values, WebKit/Safari does not consider the request to meet the conditions for a “simple request”. What WebKit/Safari considers “non-standard” values for those headers is not documented except in the following WebKit bugs: <a href="https://bugs.webkit.org/show_bug.cgi?id=165178" rel="nofollow noreferrer">Require preflight for non-standard CORS-safelisted request headers Accept, Accept-Language, and Content-Language</a>, <a href="https://bugs.webkit.org/show_bug.cgi?id=165566" rel="nofollow noreferrer">Allow commas in Accept, Accept-Language, and Content-Language request headers for simple CORS</a>, and <a href="https://bugs.webkit.org/show_bug.cgi?id=166363" rel="nofollow noreferrer">Switch to a blacklist model for restricted Accept headers in simple CORS requests</a>. No other browsers implement those extra restrictions, because they’re not part of the spec.</div> - -<p>For example, suppose web content on domain <code class="plain">http://foo.example</code> wishes to invoke content on domain <code class="plain">http://bar.other</code>. Code of this sort might be used within JavaScript deployed on foo.example:</p> - -<pre class="brush: js" id="line1">const invocation = new XMLHttpRequest(); -const url = 'http://bar.other/resources/public-data/'; - -function callOtherDomain() { - if(invocation) { - invocation.open('GET', url, true); - invocation.onreadystatechange = handler; - invocation.send(); - } -} -</pre> - -<p>This will lead to a simple exchange between the client and the server, using CORS headers to handle the privileges:</p> - -<p><img alt="" src="https://mdn.mozillademos.org/files/14293/simple_req.png" style="height: 224px; width: 521px;"></p> - -<p>Let us look at what the browser will send to the server in this case, and let's see how the server responds:</p> - -<pre class="brush: shell;highlight:[10,16]">GET /resources/public-data/ HTTP/1.1 -Host: bar.other -User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.5; en-US; rv:1.9.1b3pre) Gecko/20081130 Minefield/3.1b3pre -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 -Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7 -Connection: keep-alive -Referer: http://foo.example/examples/access-control/simpleXSInvocation.html -Origin: http://foo.example - - -HTTP/1.1 200 OK -Date: Mon, 01 Dec 2008 00:23:53 GMT -Server: Apache/2.0.61 -Access-Control-Allow-Origin: * -Keep-Alive: timeout=2, max=100 -Connection: Keep-Alive -Transfer-Encoding: chunked -Content-Type: application/xml - -[XML Data] -</pre> - -<p>Lines 1 - 10 are headers sent. The main HTTP request header of note here is the {{HTTPHeader("Origin")}} header on line 10 above, which shows that the invocation is coming from content on the domain <code class="plain">http://foo.example</code>.</p> - -<p>Lines 13 - 22 show the HTTP response from the server on domain <code class="plain">http://bar.other</code>. In response, the server sends back an {{HTTPHeader("Access-Control-Allow-Origin")}} header, shown above in line 16. The use of the {{HTTPHeader("Origin")}} header and of {{HTTPHeader("Access-Control-Allow-Origin")}} show the access control protocol in its simplest use. In this case, the server responds with a <code>Access-Control-Allow-Origin: *</code> which means that the resource can be accessed by <strong>any</strong> domain in a cross-site manner. If the resource owners at <code class="plain">http://bar.other</code> wished to restrict access to the resource to requests only from <code class="plain">http://foo.example</code>, they would send back:</p> - -<p><code class="plain">Access-Control-Allow-Origin: http://foo.example</code></p> - -<p>Note that now, no domain other than <code class="plain">http://foo.example</code> (identified by the ORIGIN: header in the request, as in line 10 above) can access the resource in a cross-site manner. The <code>Access-Control-Allow-Origin</code> header should contain the value that was sent in the request's <code>Origin</code> header.</p> - -<h3 id="Preflighted_requests">Preflighted requests</h3> - -<p>Unlike <a href="#Simple_requests">“simple requests” (discussed above)</a>, "preflighted" requests first send an HTTP request by the {{HTTPMethod("OPTIONS")}} method to the resource on the other domain, in order to determine whether the actual request is safe to send. Cross-site requests are preflighted like this since they may have implications to user data.</p> - -<p>In particular, a request is preflighted if <strong>any of the following conditions</strong> is true:</p> - -<ul> - <li><strong>If</strong> the request uses any of the following methods: - - <ul> - <li>{{HTTPMethod("PUT")}}</li> - <li>{{HTTPMethod("DELETE")}}</li> - <li>{{HTTPMethod("CONNECT")}}</li> - <li>{{HTTPMethod("OPTIONS")}}</li> - <li>{{HTTPMethod("TRACE")}}</li> - <li>{{HTTPMethod("PATCH")}}</li> - </ul> - </li> - <li><strong>Or if</strong>, apart from the headers set automatically by the user agent (for example, {{HTTPHeader("Connection")}}, {{HTTPHeader("User-Agent")}}, or <a href="https://fetch.spec.whatwg.org/#forbidden-header-name">any of the <strong>OTHER</strong> header with a name defined in the Fetch spec as a “forbidden header name”</a>), the request includes any headers other than <a href="https://fetch.spec.whatwg.org/#cors-safelisted-request-header">those which the Fetch spec defines as being a “CORS-safelisted request-header”</a>, which are the following: - <ul> - <li>{{HTTPHeader("Accept")}}</li> - <li>{{HTTPHeader("Accept-Language")}}</li> - <li>{{HTTPHeader("Content-Language")}}</li> - <li>{{HTTPHeader("Content-Type")}} (but note the additional requirements below)</li> - <li><code><a href="http://httpwg.org/http-extensions/client-hints.html#dpr">DPR</a></code></li> - <li>{{HTTPHeader("Downlink")}}</li> - <li><code><a href="http://httpwg.org/http-extensions/client-hints.html#save-data">Save-Data</a></code></li> - <li><code><a href="http://httpwg.org/http-extensions/client-hints.html#viewport-width">Viewport-Width</a></code></li> - <li><code><a href="http://httpwg.org/http-extensions/client-hints.html#width">Width</a></code></li> - </ul> - </li> - <li><strong>Or if</strong> the {{HTTPHeader("Content-Type")}} header has a value <strong>OTHER THAN</strong> the following: - <ul> - <li><code>application/x-www-form-urlencoded</code></li> - <li><code>multipart/form-data</code></li> - <li><code>text/plain</code></li> - </ul> - </li> - <li><strong>Or if</strong> one or more event listeners are registered on an {{domxref("XMLHttpRequestUpload")}} object used in the request.</li> - <li><strong>Or if</strong> a {{domxref("ReadableStream")}} object is used in the request.</li> -</ul> - -<div class="note"><strong>Note:</strong> WebKit Nightly and Safari Technology Preview place additional restrictions on the values allowed in the {{HTTPHeader("Accept")}}, {{HTTPHeader("Accept-Language")}}, and {{HTTPHeader("Content-Language")}} headers. If any of those headers have ”non-standard” values, WebKit/Safari preflights the request. What WebKit/Safari considers “non-standard” values for those headers is not documented except in the following WebKit bugs: <a href="https://bugs.webkit.org/show_bug.cgi?id=165178" rel="nofollow noreferrer">Require preflight for non-standard CORS-safelisted request headers Accept, Accept-Language, and Content-Language</a>, <a href="https://bugs.webkit.org/show_bug.cgi?id=165566" rel="nofollow noreferrer">Allow commas in Accept, Accept-Language, and Content-Language request headers for simple CORS</a>, and <a href="https://bugs.webkit.org/show_bug.cgi?id=166363" rel="nofollow noreferrer">Switch to a blacklist model for restricted Accept headers in simple CORS requests</a>. No other browsers implement those extra restrictions, because they’re not part of the spec.</div> - -<p>The following is an example of a request that will be preflighted.</p> - -<pre class="brush: js" id="line1">const invocation = new XMLHttpRequest(); -const url = 'http://bar.other/resources/post-here/'; -const body = '<?xml version="1.0"?><person><name>Arun</name></person>'; - -function callOtherDomain(){ - if(invocation) - { - invocation.open('POST', url, true); - invocation.setRequestHeader('X-PINGOTHER', 'pingpong'); - invocation.setRequestHeader('Content-Type', 'application/xml'); - invocation.onreadystatechange = handler; - invocation.send(body); - } -} - -...... -</pre> - -<p>In the example above, line 3 creates an XML body to send with the <code>POST</code> request in line 8. Also, on line 9, a "customized" (non-standard) HTTP request header is set (<code>X-PINGOTHER: pingpong</code>). Such headers are not part of the HTTP/1.1 protocol, but are generally useful to web applications. Since the request uses a Content-Type of <code>application/xml</code>, and since a custom header is set, this request is preflighted.</p> - -<p><img alt="" src="https://mdn.mozillademos.org/files/16401/preflight_.png" style="height: 555px; width: 538px;"></p> - -<p>(Note: as described below, the actual POST request does not include the Access-Control-Request-* headers; they are needed only for the OPTIONS request.)</p> - -<p>Let's take a look at the full exchange between client and server. The first exchange is the <em>preflight request/response</em>:</p> - -<pre class="brush: none;highlight:[1,10,11,17-20]">OPTIONS /resources/post-here/ HTTP/1.1 -Host: bar.other -User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.5; en-US; rv:1.9.1b3pre) Gecko/20081130 Minefield/3.1b3pre -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 -Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7 -Connection: keep-alive -Origin: http://foo.example -Access-Control-Request-Method: POST -Access-Control-Request-Headers: X-PINGOTHER, Content-Type - - -HTTP/1.1 204 No Content -Date: Mon, 01 Dec 2008 01:15:39 GMT -Server: Apache/2.0.61 (Unix) -Access-Control-Allow-Origin: http://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 -</pre> - -<p>Once the preflight request is complete, the real request is sent:</p> - -<pre class="brush: none;">POST /resources/post-here/ HTTP/1.1 -Host: bar.other -User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.5; en-US; rv:1.9.1b3pre) Gecko/20081130 Minefield/3.1b3pre -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 -Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7 -Connection: keep-alive -X-PINGOTHER: pingpong -Content-Type: text/xml; charset=UTF-8 -Referer: http://foo.example/examples/preflightInvocation.html -Content-Length: 55 -Origin: http://foo.example -Pragma: no-cache -Cache-Control: no-cache - -<?xml version="1.0"?><person><name>Arun</name></person> - - -HTTP/1.1 200 OK -Date: Mon, 01 Dec 2008 01:15:40 GMT -Server: Apache/2.0.61 (Unix) -Access-Control-Allow-Origin: http://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 GZIP'd payload] -</pre> - -<p>Lines 1 - 12 above represent the preflight request with the {{HTTPMethod("OPTIONS")}} method. 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 a {{Glossary("safe")}} method, meaning that it can't be used to change the resource. Note that along with the OPTIONS request, two other request headers are sent (lines 10 and 11 respectively):</p> - -<pre class="brush: none">Access-Control-Request-Method: POST -Access-Control-Request-Headers: X-PINGOTHER, Content-Type -</pre> - -<p>The {{HTTPHeader("Access-Control-Request-Method")}} header notifies the server as part of a preflight request that when the actual request is sent, it will be sent with a <code>POST</code> request method. The {{HTTPHeader("Access-Control-Request-Headers")}} header notifies the server that when the actual request is sent, it will be sent with a <code>X-PINGOTHER</code> and <code>Content-Type</code> custom headers. The server now has an opportunity to determine whether it wishes to accept a request under these circumstances.</p> - -<p>Lines 14 - 26 above are the response that the server sends back indicating that the request method (<code>POST</code>) and request headers (<code>X-PINGOTHER</code>) are acceptable. In particular, let's look at lines 17-20:</p> - -<pre class="brush: none">Access-Control-Allow-Origin: http://foo.example -Access-Control-Allow-Methods: POST, GET -Access-Control-Allow-Headers: X-PINGOTHER, Content-Type -Access-Control-Max-Age: 86400</pre> - -<p>The server responds with <code>Access-Control-Allow-Methods</code> and says that <code>POST</code> and <code>GET</code> are viable methods to query the resource in question. Note that this header is similar to the {{HTTPHeader("Allow")}} response header, but used strictly within the context of access control.</p> - -<p>The server also sends <code>Access-Control-Allow-Headers</code> with a value of "<code>X-PINGOTHER, Content-Type</code>", confirming that these are permitted headers to be used with the actual request. Like <code>Access-Control-Allow-Methods</code>, <code>Access-Control-Allow-Headers</code> is a comma separated list of acceptable headers.</p> - -<p>Finally, {{HTTPHeader("Access-Control-Max-Age")}} gives the value in seconds for how long the response to the preflight request can be cached for without sending another preflight request. In this case, 86400 seconds is 24 hours. Note that each browser has a <a href="/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age">maximum internal value</a> that takes precedence when the <code>Access-Control-Max-Age</code> is greater.</p> - -<h4 id="Preflighted_requests_and_redirects">Preflighted requests and redirects</h4> - -<p>Not all browsers currently support following redirects after a preflighted request. If a redirect occurs after a preflighted request, some browsers currently will report an error message such as the following.</p> - -<blockquote> -<p>The request was redirected to 'https://example.com/foo', which is disallowed for cross-origin requests that require preflight</p> -</blockquote> - -<blockquote> -<p>Request requires preflight, which is disallowed to follow cross-origin redirect</p> -</blockquote> - -<p>The CORS protocol originally required that behavior but <a href="https://github.com/whatwg/fetch/commit/0d9a4db8bc02251cc9e391543bb3c1322fb882f2">was subsequently changed to no longer require it</a>. However, not all browsers have implemented the change, and so still exhibit the behavior that was originally required.</p> - -<p>So until all browsers catch up with the spec, you may be able to work around this limitation by doing one or both of the following:</p> - -<ul> - <li>change the server-side behavior to avoid the preflight and/or to avoid the redirect—if you have control over the server the request is being made to</li> - <li>change the request such that it is a <a href="#Simple_requests">simple request</a> that doesn’t cause a preflight</li> -</ul> - -<p>But if it’s not possible to make those changes, then another way that may be possible is to this:</p> - -<ol> - <li>Make a <a href="#Simple_requests">simple request</a> (using {{domxref("Response.url")}} for the Fetch API, or {{domxref("XMLHttpRequest.responseURL")}}) to determine what URL the real preflighted request would end up at.</li> - <li>Make another request (the “real” request) using the URL you obtained from <code>Response.url</code> or <code>XMLHttpRequest.responseURL</code> in the first step.</li> -</ol> - -<p>However, if the request is one that triggers a preflight due to the presence of the <code>Authorization</code> header 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.</p> - -<h3 id="Requests_with_credentials">Requests with credentials</h3> - -<p>The most interesting capability exposed by both {{domxref("XMLHttpRequest")}} or <a href="/en-US/docs/Web/API/Fetch_API">Fetch</a> and CORS is the ability to make "credentialed" requests that are aware of <a href="/en-US/docs/Web/HTTP/Cookies">HTTP cookies</a> and HTTP Authentication information. By default, in cross-site <code>XMLHttpRequest</code> or <a href="/en-US/docs/Web/API/Fetch_API">Fetch</a> invocations, browsers will <strong>not</strong> send credentials. A specific flag has to be set on the <code>XMLHttpRequest</code> object or the {{domxref("Request")}} constructor when it is invoked.</p> - -<p>In this example, content originally loaded from <code class="plain">http://foo.example</code> makes a simple GET request to a resource on <code class="plain">http://bar.other</code> which sets Cookies. Content on foo.example might contain JavaScript like this:</p> - -<pre class="brush: js" id="line1">const invocation = new XMLHttpRequest(); -const url = 'http://bar.other/resources/credentialed-content/'; - -function callOtherDomain(){ - if(invocation) { - invocation.open('GET', url, true); - invocation.withCredentials = true; - invocation.onreadystatechange = handler; - invocation.send(); - } -}</pre> - -<p>Line 7 shows the flag on {{domxref("XMLHttpRequest")}} that has to be set in order to make the invocation with Cookies, namely the <code>withCredentials</code> boolean value. By default, the invocation is made without Cookies. Since this is a simple <code>GET</code> request, it is not preflighted, but the browser will <strong>reject</strong> any response that does not have the {{HTTPHeader("Access-Control-Allow-Credentials")}}<code>: true</code> header, and <strong>not</strong> make the response available to the invoking web content.</p> - -<p><img alt="" src="https://mdn.mozillademos.org/files/14291/cred-req.png" style="height: 223px; width: 521px;"></p> - -<p>Here is a sample exchange between client and server:</p> - -<pre class="brush: none">GET /resources/access-control-with-credentials/ HTTP/1.1 -Host: bar.other -User-Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.5; en-US; rv:1.9.1b3pre) Gecko/20081130 Minefield/3.1b3pre -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 -Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7 -Connection: keep-alive -Referer: http://foo.example/examples/credential.html -Origin: http://foo.example -Cookie: pageAccess=2 - - -HTTP/1.1 200 OK -Date: Mon, 01 Dec 2008 01:34:52 GMT -Server: Apache/2.0.61 (Unix) PHP/4.4.7 mod_ssl/2.0.61 OpenSSL/0.9.7e mod_fastcgi/2.4.2 DAV/2 SVN/1.4.2 -X-Powered-By: PHP/5.2.6 -Access-Control-Allow-Origin: http://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] -</pre> - -<p>Although line 11 contains the Cookie destined for the content on <code class="plain">http://bar.other</code>, if bar.other did not respond with an {{HTTPHeader("Access-Control-Allow-Credentials")}}<code>: true</code> (line 19) the response would be ignored and not made available to web content.</p> - -<h4 id="Credentialed_requests_and_wildcards">Credentialed requests and wildcards</h4> - -<p>When responding to a credentialed request, the server <strong>must</strong> specify an origin in the value of the <code>Access-Control-Allow-Origin</code> header, instead of specifying the "<code>*</code>" wildcard.</p> - -<p>Because the request headers in the above example include a <code>Cookie</code> header, the request would fail if the value of the <code>Access-Control-Allow-Origin</code> header were "*". But it does not fail: Because the value of the <code>Access-Control-Allow-Origin</code> header is "<code class="plain">http://foo.example</code>" (an actual origin) rather than the "<code>*</code>" wildcard, the credential-cognizant content is returned to the invoking web content.</p> - -<p>Note that the <code>Set-Cookie</code> response header in the example above also sets a further cookie. In case of failure, an exception—depending on the API used—is raised.</p> - -<h4 id="Third-party_cookies">Third-party cookies</h4> - -<p>Note that cookies set in CORS responses are subject to normal third-party cookie policies. In the example above, the page is loaded from <code>foo.example</code>, but the cookie on line 22 is sent by <code>bar.other</code>, and would thus not be saved if the user has configured their browser to reject all third-party cookies.</p> - -<h2 id="The_HTTP_response_headers">The HTTP response headers</h2> - -<p>This section lists the HTTP response headers that servers send back for access control requests as defined by the Cross-Origin Resource Sharing specification. The previous section gives an overview of these in action.</p> - -<h3 id="Access-Control-Allow-Origin">Access-Control-Allow-Origin</h3> - -<p>A returned resource may have one {{HTTPHeader("Access-Control-Allow-Origin")}} header, with the following syntax:</p> - -<pre class="brush: none">Access-Control-Allow-Origin: <origin> | * -</pre> - -<p><code>Access-Control-Allow-Origin</code> specifies either a single origin, which tells browsers to allow that origin to access the resource; or else — for requests <strong>without</strong> credentials — the "<code>*</code>" wildcard, to tell browsers to allow any origin to access the resource.</p> - -<p>For example, to allow code from the origin <code>http://mozilla.org</code> to access the resource, you can specify:</p> - -<pre class="brush: none">Access-Control-Allow-Origin: http://mozilla.org</pre> - -<p>If the server specifies a single origin rather than the "<code>*</code>" wildcard, then the server should also include <code>Origin</code> in the {{HTTPHeader("Vary")}} response header — to indicate to clients that server responses will differ based on the value of the {{HTTPHeader("Origin")}} request header.</p> - -<h3 id="Access-Control-Expose-Headers">Access-Control-Expose-Headers</h3> - -<p>The {{HTTPHeader("Access-Control-Expose-Headers")}} header lets a server whitelist headers that browsers are allowed to access.</p> - -<pre class="brush: none">Access-Control-Expose-Headers: <field-name>[, <field-name>]* -</pre> - -<p>For example, the following:</p> - -<pre class="brush: none">Access-Control-Expose-Headers: X-My-Custom-Header, X-Another-Custom-Header -</pre> - -<p>…would allow the <code>X-My-Custom-Header</code> and <code>X-Another-Custom-Header</code> headers to be exposed to the browser.</p> - -<h3 id="Access-Control-Max-Age">Access-Control-Max-Age</h3> - -<p>The {{HTTPHeader("Access-Control-Max-Age")}} header indicates how long the results of a preflight request can be cached. For an example of a preflight request, see the above examples.</p> - -<pre class="brush: none">Access-Control-Max-Age: <delta-seconds> -</pre> - -<p>The <code>delta-seconds</code> parameter indicates the number of seconds the results can be cached.</p> - -<h3 id="Access-Control-Allow-Credentials">Access-Control-Allow-Credentials</h3> - -<p>The {{HTTPHeader("Access-Control-Allow-Credentials")}} header Indicates whether or not the response to the request can be exposed when the <code>credentials</code> flag 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 simple <code>GET</code> requests 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.</p> - -<pre class="brush: none">Access-Control-Allow-Credentials: true -</pre> - -<p><a class="internal" href="#Requests_with_credentials">Credentialed requests</a> are discussed above.</p> - -<h3 id="Access-Control-Allow-Methods">Access-Control-Allow-Methods</h3> - -<p>The {{HTTPHeader("Access-Control-Allow-Methods")}} header 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.</p> - -<pre class="brush: none">Access-Control-Allow-Methods: <method>[, <method>]* -</pre> - -<p>An example of a <a class="internal" href="#Preflighted_requests">preflight request is given above</a>, including an example which sends this header to the browser.</p> - -<h3 id="Access-Control-Allow-Headers">Access-Control-Allow-Headers</h3> - -<p>The {{HTTPHeader("Access-Control-Allow-Headers")}} header is used in response to a <a class="internal" href="#Preflighted_requests">preflight request</a> to indicate which HTTP headers can be used when making the actual request.</p> - -<pre class="brush: none">Access-Control-Allow-Headers: <field-name>[, <field-name>]* -</pre> - -<h2 id="The_HTTP_request_headers">The HTTP request headers</h2> - -<p>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 using cross-site {{domxref("XMLHttpRequest")}} capability do not have to set any cross-origin sharing request headers programmatically.</p> - -<h3 id="Origin">Origin</h3> - -<p>The {{HTTPHeader("Origin")}} header indicates the origin of the cross-site access request or preflight request.</p> - -<pre class="brush: none">Origin: <origin> -</pre> - -<p>The origin is a URI indicating the server from which the request initiated. It does not include any path information, but only the server name.</p> - -<div class="note"><strong>Note:</strong> The <code>origin</code> value can be <code>null</code>, or a URI.</div> - -<p>Note that in any access control request, the {{HTTPHeader("Origin")}} header is <strong>always</strong> sent.</p> - -<h3 id="Access-Control-Request-Method">Access-Control-Request-Method</h3> - -<p>The {{HTTPHeader("Access-Control-Request-Method")}} is used when issuing a preflight request to let the server know what HTTP method will be used when the actual request is made.</p> - -<pre class="brush: none">Access-Control-Request-Method: <method> -</pre> - -<p>Examples of this usage can be <a class="internal" href="#Preflighted_requests">found above.</a></p> - -<h3 id="Access-Control-Request-Headers">Access-Control-Request-Headers</h3> - -<p>The {{HTTPHeader("Access-Control-Request-Headers")}} header is used when issuing a preflight request to let the server know what HTTP headers will be used when the actual request is made.</p> - -<pre class="brush: none">Access-Control-Request-Headers: <field-name>[, <field-name>]* -</pre> - -<p>Examples of this usage can be <a class="internal" href="#Preflighted_requests">found above</a>.</p> - -<h2 id="Specifications">Specifications</h2> - -<table class="standard-table"> - <tbody> - <tr> - <th scope="col">Specification</th> - <th scope="col">Status</th> - <th scope="col">Comment</th> - </tr> - <tr> - <td>{{SpecName('Fetch', '#cors-protocol', 'CORS')}}</td> - <td>{{Spec2('Fetch')}}</td> - <td>New definition; supplants <a href="https://www.w3.org/TR/cors/">W3C CORS</a> specification.</td> - </tr> - </tbody> -</table> - -<h2 id="Browser_compatibility">Browser compatibility</h2> - -<p class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</p> - -<p>{{Compat("http.headers.Access-Control-Allow-Origin")}}</p> - -<h3 id="Compatibility_notes">Compatibility notes</h3> - -<ul> - <li>Internet Explorer 8 and 9 expose CORS via the <code>XDomainRequest</code> object, but have a full implementation in IE 10.</li> - <li>While Firefox 3.5 introduced support for cross-site <code>XMLHttpRequests</code> and Web Fonts, certain requests were limited until later versions. Specifically, Firefox 7 introduced the ability for cross-site HTTP requests for WebGL Textures, and Firefox 9 added support for Images drawn on a canvas using <code>drawImage()</code>.</li> -</ul> - -<h2 id="See_also">See also</h2> - -<ul> - <li><a href="/en-US/docs/Web/HTTP/CORS/Errors">CORS errors</a></li> - <li><a href="https://enable-cors.org/server.html">Enable CORS: I want to add CORS support to my server</a></li> - <li>{{domxref("XMLHttpRequest")}}</li> - <li><a href="/en-US/docs/Web/API/Fetch_API">Fetch API</a></li> - <li><a class="external" href="http://www.kendoui.com/blogs/teamblog/posts/11-10-03/using_cors_with_all_modern_browsers.aspx">Using CORS with All (Modern) Browsers</a></li> - <li><a href="http://www.html5rocks.com/en/tutorials/cors/">Using CORS - HTML5 Rocks</a> - <ul> - </ul> - </li> - <li><a class="external" href="https://arunranga.com/examples/access-control/">Code Samples Showing <code>XMLHttpRequest</code> and Cross-Origin Resource Sharing</a></li> - <li><a href="https://github.com/jackblackevo/cors-jsonp-sample">Client-Side & Server-Side (Java) sample for Cross-Origin Resource Sharing (CORS)</a></li> - <li><a class="internal" href="/en-US/docs/Web/HTTP/Server-Side_Access_Control">Cross-Origin Resource Sharing From a Server-Side Perspective (PHP, etc.)</a></li> - <li><a href="https://stackoverflow.com/questions/43871637/no-access-control-allow-origin-header-is-present-on-the-requested-resource-whe/43881141#43881141">Stack Overflow answer with “how to” info for dealing with common problems</a>: - <ul> - <li>How to avoid the CORS preflight</li> - <li>How to use a CORS proxy to get around <em>“No Access-Control-Allow-Origin header”</em></li> - <li>How to fix <em>“Access-Control-Allow-Origin header must not be the wildcard”</em></li> - </ul> - </li> -</ul> |