Access-Control-Allow-Headers等基礎常識

跨源資源共享 (CORS) （或通俗地譯為跨域資源共享）是一種機制，該機制使用附加的 HTTP 頭來告訴瀏覽器，准許運行在一個源上的Web應用訪問位於另一不同源選定的資源。 當一個Web應用發起一個與自身所在源（域，協議和端口）不同的HTTP請求時，它發起的即跨源HTTP請求。

跨源HTTP請求的一個例子：運行在 http://domain-a.com 的JavaScript代碼使用XMLHttpRequest來發起一個到 https://domain-b.com/data.json 的請求。

出於安全性，瀏覽器限制腳本內發起的跨源HTTP請求。 例如，XMLHttpRequest和Fetch API遵循同源策略。 這意味着使用這些API的Web應用程序只能從加載應用程序的同一個域請求HTTP資源，除非響應報文包含了正確CORS響應頭。

跨源域資源共享（ CORS ）機制允許 Web 應用服務器進行跨源訪問控制，從而使跨源數據傳輸得以安全進行。現代瀏覽器支持在 API 容器中（例如 XMLHttpRequest 或 Fetch ）使用 CORS，以降低跨源 HTTP 請求所帶來的風險。

誰應該讀這篇文章？

說實話，每個人。

更具體地來講，這篇文章適用於網站管理員、后端和前端開發者。現代瀏覽器處理跨源資源共享的客戶端部分，包括HTTP頭和相關策略的執行。但是這一新標准意味着服務器需要處理新的請求頭和響應頭。對於服務端的支持，開發者可以閱讀補充材料 cross-origin sharing from a server perspective (with PHP code snippets) 。

什么情況下需要 CORS ？

這份 cross-origin sharing standard 允許在下列場景中使用跨站點 HTTP 請求：

• 前文提到的由 XMLHttpRequest 或 Fetch 發起的跨源 HTTP 請求。
• Web 字體 (CSS 中通過 @font-face 使用跨源字體資源)，因此，網站就可以發布 TrueType 字體資源，並只允許已授權網站進行跨站調用。
• WebGL 貼圖
• 使用 drawImage 將 Images/video 畫面繪制到 canvas

本文概述了跨源資源共享機制及其所涉及的 HTTP 頭。

功能概述

跨源資源共享標准新增了一組 HTTP 首部字段，允許服務器聲明哪些源站通過瀏覽器有權限訪問哪些資源。另外，規范要求，對那些可能對服務器數據產生副作用的 HTTP 請求方法（特別是 GET 以外的 HTTP 請求，或者搭配某些 MIME 類型的 POST 請求），瀏覽器必須首先使用 OPTIONS 方法發起一個預檢請求（preflight request），從而獲知服務端是否允許該跨源請求。服務器確認允許之后，才發起實際的 HTTP 請求。在預檢請求的返回中，服務器端也可以通知客戶端，是否需要攜帶身份憑證（包括 Cookies 和 HTTP 認證相關數據）。

CORS請求失敗會產生錯誤，但是為了安全，在JavaScript代碼層面是無法獲知到底具體是哪里出了問題。你只能查看瀏覽器的控制台以得知具體是哪里出現了錯誤。

接下來的內容將討論相關場景，並剖析該機制所涉及的 HTTP 首部字段。

若干訪問控制場景

這里，我們使用三個場景來解釋跨源資源共享機制的工作原理。這些例子都使用 XMLHttpRequest 對象。

本文中的 JavaScript 代碼片段都可以從 http://arunranga.com/examples/access-control/ 獲得。另外，使用支持跨源  XMLHttpRequest 的瀏覽器訪問該地址，可以看到代碼的實際運行結果。

關於服務端對跨源資源共享的支持的討論，請參見這篇文章： Server-Side_Access_Control (CORS)。

簡單請求

某些請求不會觸發 CORS 預檢請求。本文稱這樣的請求為“簡單請求”，請注意，該術語並不屬於 Fetch （其中定義了 CORS）規范。若請求滿足所有下述條件，則該請求可視為“簡單請求”：

• 使用下列方法之一：
  • GET
  • HEAD
  • POST
• 除了被用戶代理自動設置的首部字段（例如 Connection ，User-Agent）和在 Fetch 規范中定義為 禁用首部名稱 的其他首部，允許人為設置的字段為 Fetch 規范定義的 對 CORS 安全的首部字段集合。該集合為：
  • Accept
  • Accept-Language
  • Content-Language
  • Content-Type （需要注意額外的限制）
  • DPR
  • Downlink
  • Save-Data
  • Viewport-Width
  • Width
• Content-Type 的值僅限於下列三者之一：
  • text/plain
  • multipart/form-data
  • application/x-www-form-urlencoded
• 請求中的任意XMLHttpRequestUpload 對象均沒有注冊任何事件監聽器；XMLHttpRequestUpload 對象可以使用 XMLHttpRequest.upload 屬性訪問。
• 請求中沒有使用 ReadableStream 對象。

注意: 這些跨站點請求與瀏覽器發出的其他跨站點請求並無二致。如果服務器未返回正確的響應首部，則請求方不會收到任何數據。因此，那些不允許跨站點請求的網站無需為這一新的 HTTP 訪問控制特性擔心。

注意: WebKit Nightly 和 Safari Technology Preview 為 Accept,  Accept-Language, 和  Content-Language 首部字段的值添加了額外的限制。如果這些首部字段的值是“非標准”的，WebKit/Safari 就不會將這些請求視為“簡單請求”。WebKit/Safari 並沒有在文檔中列出哪些值是“非標准”的，不過我們可以在這里找到相關討論： Require preflight for non-standard CORS-safelisted request headers Accept, Accept-Language, and Content-Language,  Allow commas in Accept, Accept-Language, and Content-Language request headers for simple CORS, and  Switch to a blacklist model for restricted Accept headers in simple CORS requests。其它瀏覽器並不支持這些額外的限制，因為它們不屬於規范的一部分。

比如說，假如站點 http://foo.example 的網頁應用想要訪問 http://bar.other 的資源。http://foo.example 的網頁中可能包含類似於下面的 JavaScript 代碼：

var invocation = new XMLHttpRequest(); var url = 'http://bar.other/resources/public-data/'; function callOtherDomain() { if(invocation) { invocation.open('GET', url, true); invocation.onreadystatechange = handler; invocation.send(); } } 

客戶端和服務器之間使用 CORS 首部字段來處理權限：

分別檢視請求報文和響應報文：

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] 

第 1~10 行是請求首部。第10行 的請求首部字段 Origin 表明該請求來源於 http://foo.example。

第 13~22 行是來自於 http://bar.other 的服務端響應。響應中攜帶了響應首部字段 Access-Control-Allow-Origin（第 16 行）。使用 Origin 和 Access-Control-Allow-Origin 就能完成最簡單的訪問控制。本例中，服務端返回的 Access-Control-Allow-Origin: * 表明，該資源可以被任意外域訪問。如果服務端僅允許來自 http://foo.example 的訪問，該首部字段的內容如下：

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

現在，除了 http://foo.example，其它外域均不能訪問該資源（該策略由請求首部中的 ORIGIN 字段定義，見第10行）。Access-Control-Allow-Origin 應當為 * 或者包含由 Origin 首部字段所指明的域名。

預檢請求

與前述簡單請求不同，“需預檢的請求”要求必須首先使用 OPTIONS   方法發起一個預檢請求到服務器，以獲知服務器是否允許該實際請求。"預檢請求“的使用，可以避免跨域請求對服務器的用戶數據產生未預期的影響。

如下是一個需要執行預檢請求的 HTTP 請求：

var invocation = new XMLHttpRequest(); var url = 'http://bar.other/resources/post-here/'; var 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); } } ...... 

上面的代碼使用 POST 請求發送一個 XML 文檔，該請求包含了一個自定義的請求首部字段（X-PINGOTHER: pingpong）。另外，該請求的 Content-Type 為 application/xml。因此，該請求需要首先發起“預檢請求”。

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 200 OK
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
Content-Encoding: gzip
Content-Length: 0
Keep-Alive: timeout=2, max=100
Connection: Keep-Alive
Content-Type: text/plain

預檢請求完成之后，發送實際請求：

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]

瀏覽器檢測到，從 JavaScript 中發起的請求需要被預檢。從上面的報文中，我們看到，第 1~12 行發送了一個使用 OPTIONS 方法的“預檢請求”。 OPTIONS 是 HTTP/1.1 協議中定義的方法，用以從服務器獲取更多信息。該方法不會對服務器資源產生影響。 預檢請求中同時攜帶了下面兩個首部字段：

Access-Control-Request-Method: POST
Access-Control-Request-Headers: X-PINGOTHER, Content-Type

首部字段 Access-Control-Request-Method 告知服務器，實際請求將使用 POST 方法。首部字段 Access-Control-Request-Headers 告知服務器，實際請求將攜帶兩個自定義請求首部字段：X-PINGOTHER 與 Content-Type。服務器據此決定，該實際請求是否被允許。

第14~26 行為預檢請求的響應，表明服務器將接受后續的實際請求。重點看第 17~20 行：

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

首部字段 Access-Control-Allow-Methods 表明服務器允許客戶端使用 POST, GET 和 OPTIONS 方法發起請求。該字段與 HTTP/1.1 Allow: response header 類似，但僅限於在需要訪問控制的場景中使用。

首部字段 Access-Control-Allow-Headers 表明服務器允許請求中攜帶字段 X-PINGOTHER 與 Content-Type。與 Access-Control-Allow-Methods 一樣，Access-Control-Allow-Headers 的值為逗號分割的列表。

最后，首部字段 Access-Control-Max-Age 表明該響應的有效時間為 86400 秒，也就是 24 小時。在有效時間內，瀏覽器無須為同一請求再次發起預檢請求。請注意，瀏覽器自身維護了一個最大有效時間，如果該首部字段的值超過了最大有效時間，將不會生效。

預檢請求與重定向

大多數瀏覽器不支持針對於預檢請求的重定向。如果一個預檢請求發生了重定向，瀏覽器將報告錯誤：

The request was redirected to 'https://example.com/foo', which is disallowed for cross-origin requests that require preflight

Request requires preflight, which is disallowed to follow cross-origin redirect

CORS 最初要求該行為，不過在后續的修訂中廢棄了這一要求。

在瀏覽器的實現跟上規范之前，有兩種方式規避上述報錯行為：

• 在服務端去掉對預檢請求的重定向；
• 將實際請求變成一個簡單請求。

如果上面兩種方式難以做到，我們仍有其他辦法：

• 發出一個簡單請求（使用  Response.url 或 XHR.responseURL）以判斷真正的預檢請求會返回什么地址。
• 發出另一個請求（真正的請求），使用在上一步通過Response.url 或 XMLHttpRequest.responseURL獲得的URL。

不過，如果請求是由於存在 Authorization 字段而引發了預檢請求，則這一方法將無法使用。這種情況只能由服務端進行更改。

附帶身份憑證的請求

XMLHttpRequest 或 Fetch 與 CORS 的一個有趣的特性是，可以基於  HTTP cookies 和 HTTP 認證信息發送身份憑證。一般而言，對於跨源 XMLHttpRequest 或 Fetch 請求，瀏覽器不會發送身份憑證信息。如果要發送憑證信息，需要設置 XMLHttpRequest 的某個特殊標志位。

本例中，http://foo.example 的某腳本向 http://bar.other 發起一個GET 請求，並設置 Cookies：

var invocation = new XMLHttpRequest();
var url = 'http://bar.other/resources/credentialed-content/';
    
function callOtherDomain(){
  if(invocation) {
    invocation.open('GET', url, true);
    invocation.withCredentials = true;
    invocation.onreadystatechange = handler;
    invocation.send(); 
  }
}

第 7 行將 XMLHttpRequest 的 withCredentials 標志設置為 true，從而向服務器發送 Cookies。因為這是一個簡單 GET 請求，所以瀏覽器不會對其發起“預檢請求”。但是，如果服務器端的響應中未攜帶 Access-Control-Allow-Credentials: true ，瀏覽器將不會把響應內容返回給請求的發送者。

客戶端與服務器端交互示例如下：

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
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
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]

即使第 10 行指定了 Cookie 的相關信息，但是，如果 bar.other 的響應中缺失 Access-Control-Allow-Credentials: true（第 17 行），則響應內容不會返回給請求的發起者。

附帶身份憑證的請求與通配符

對於附帶身份憑證的請求，服務器不得設置 Access-Control-Allow-Origin 的值為“*”。

這是因為請求的首部中攜帶了 Cookie 信息，如果 Access-Control-Allow-Origin 的值為“*”，請求將會失敗。而將 Access-Control-Allow-Origin 的值設置為 http://foo.example，則請求將成功執行。

另外，響應首部中也攜帶了 Set-Cookie 字段，嘗試對 Cookie 進行修改。如果操作失敗，將會拋出異常。

第三方 cookies

注意在 CORS 響應中設置的 cookies 適用一般性第三方 cookie 策略。在上面的例子中，頁面是在 `foo.example` 加載，但是第 20 行的 cookie 是被 `bar.other` 發送的，如果用戶設置其瀏覽器拒絕所有第三方 cookies，那么將不會被保存。

HTTP 響應首部字段

本節列出了規范所定義的響應首部字段。上一小節中，我們已經看到了這些首部字段在實際場景中是如何工作的。

Access-Control-Allow-Origin

響應首部中可以攜帶一個 Access-Control-Allow-Origin 字段，其語法如下:

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

其中，origin 參數的值指定了允許訪問該資源的外域 URI。對於不需要攜帶身份憑證的請求，服務器可以指定該字段的值為通配符，表示允許來自所有域的請求。

例如，下面的字段值將允許來自 http://mozilla.com 的請求：

Access-Control-Allow-Origin: http://mozilla.com

如果服務端指定了具體的域名而非“*”，那么響應首部中的 Vary 字段的值必須包含 Origin。這將告訴客戶端：服務器對不同的源站返回不同的內容。

Access-Control-Expose-Headers

譯者注：在跨源訪問時，XMLHttpRequest對象的getResponseHeader()方法只能拿到一些最基本的響應頭，Cache-Control、Content-Language、Content-Type、Expires、Last-Modified、Pragma，如果要訪問其他頭，則需要服務器設置本響應頭。

Access-Control-Expose-Headers 頭讓服務器把允許瀏覽器訪問的頭放入白名單，例如：

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

這樣瀏覽器就能夠通過getResponseHeader訪問X-My-Custom-Header和 X-Another-Custom-Header 響應頭了。

Access-Control-Max-Age

Access-Control-Max-Age 頭指定了preflight請求的結果能夠被緩存多久，請參考本文在前面提到的preflight例子。

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

delta-seconds 參數表示preflight請求的結果在多少秒內有效。

Access-Control-Allow-Credentials

Access-Control-Allow-Credentials 頭指定了當瀏覽器的credentials設置為true時是否允許瀏覽器讀取response的內容。當用在對preflight預檢測請求的響應中時，它指定了實際的請求是否可以使用credentials。請注意：簡單 GET 請求不會被預檢；如果對此類請求的響應中不包含該字段，這個響應將被忽略掉，並且瀏覽器也不會將相應內容返回給網頁。

Access-Control-Allow-Credentials: true

上文已經討論了附帶身份憑證的請求。

Access-Control-Allow-Methods

Access-Control-Allow-Methods 首部字段用於預檢請求的響應。其指明了實際請求所允許使用的 HTTP 方法。

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

相關示例見這里。

Access-Control-Allow-Headers

Access-Control-Allow-Headers 首部字段用於預檢請求的響應。其指明了實際請求中允許攜帶的首部字段。

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

HTTP 請求首部字段

本節列出了可用於發起跨源請求的首部字段。請注意，這些首部字段無須手動設置。 當開發者使用 XMLHttpRequest 對象發起跨源請求時，它們已經被設置就緒。

Origin

Origin 首部字段表明預檢請求或實際請求的源站。

Origin: <origin> 

origin 參數的值為源站 URI。它不包含任何路徑信息，只是服務器名稱。

Note: 有時候將該字段的值設置為空字符串是有用的，例如，當源站是一個 data URL 時。

注意，在所有訪問控制請求（Access control request）中，Origin 首部字段總是被發送。

Access-Control-Request-Method

Access-Control-Request-Method 首部字段用於預檢請求。其作用是，將實際請求所使用的 HTTP 方法告訴服務器。

Access-Control-Request-Method: <method> 

相關示例見這里。

Access-Control-Request-Headers

Access-Control-Request-Headers 首部字段用於預檢請求。其作用是，將實際請求所攜帶的首部字段告訴服務器。

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

相關示例見這里。

規范

Specification	Status	Comment
Fetch CORS	Living Standard	New definition; supplants CORS specification.
Unknown	Unknown	Initial definition.

瀏覽器兼容性

Update compatibility data on GitHub

	Desktop						Mobile
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
Access-Control-Allow-Origin	Full support4	Full support12	Full support3.5	Full support10	Full support12	Full support4	Full support2	Full supportYes	Full support4	Full support12	Full support3.2	Full supportYes