網頁可以向另一個來源的伺服器請求數據,但瀏覽器中的 JavaScript 未必能夠讀取該回應。跨來源資源共享(cross-origin resource sharing,簡稱 CORS)是一套協定,伺服器可藉此告訴瀏覽器,哪些跨來源回應可以向發出請求的網頁公開。理解 CORS 最簡單的方法,是把三個問題分開來看:請求有沒有送出?伺服器有沒有執行操作?發出調用的 JavaScript 可否讀取回應?
以下的協定訊息與程式碼是教學例子,使用保留的主機名稱 example.test,並不描述任何特定服務的技術堆疊。
1. 追蹤請求之前,先確定來源
來源(origin)是協定(scheme)、主機(host)和連接埠(port)三者的組合。例如,https://app.example.test 與 https://api.example.test 雖然屬於同一個上層網域,但由於主機不同,所以是不同的來源。同樣地,把 HTTPS 改為 HTTP,或者更改連接埠,都會改變來源。單單更改路徑或查詢字串則不會。
定義 7.1.1
(來源與 CORS)
來源(origin)是協定、主機和連接埠三者的組合。跨來源資源共享(CORS)是伺服器藉回應標頭表明哪些其他來源可以讀取其回應的協定。瀏覽器對網頁內容執行這項決定,只有標頭容許時,才把回應公開給發出調用的腳本。
同源政策(same-origin policy)限制網頁存取跨來源的回應。CORS 提供一個受控的例外:伺服器可以傳回合適的回應標頭,而瀏覽器會根據請求的來源及憑證模式(credentials mode)核對這些標頭。CORS 是由瀏覽器針對網頁內容的存取而執行的;它並不能阻止任意非瀏覽器的用戶端發送請求。伺服器仍然必須獨立地為操作進行身份驗證及授權。
2. 瀏覽器何時發送預檢?
發送跨來源請求之前,瀏覽器會先為請求分類。同時符合以下條件的請求無需預檢:方法是 GET、HEAD 或 POST;腳本設定的每個標頭都在 CORS 安全清單內(例如 Accept、Accept-Language、Content-Language、Content-Type 及簡單的 Range,其值另有限制);而 Content-Type 若存在,必須是 application/x-www-form-urlencoded、multipart/form-data 或 text/plain。另有少數條件涉及上傳事件監聽器和串流內容。其他請求都屬非簡單請求,包括 PUT、PATCH、DELETE 方法,任何自訂標頭或 Authorization 標頭,以及 Content-Type: application/json。
定義 7.1.2
(預檢請求)
預檢請求是瀏覽器在發送非簡單的跨來源請求之前,自行發出的 OPTIONS 請求。它不附帶憑證,也不附帶網頁的請求內容。Access-Control-Request-Method 指明擬使用的方法,Access-Control-Request-Headers 列出非安全清單標頭。只有回應的狀態碼表示成功,並且允許該來源、該方法及所列的每個標頭,瀏覽器才會發送實際請求。
伺服器以 Access-Control-Allow-Origin、Access-Control-Allow-Methods 和 Access-Control-Allow-Headers 回應預檢,亦可加上 Access-Control-Max-Age,讓瀏覽器把許可快取若干秒(上限由瀏覽器決定)。簡單請求會跳過這一步,這會帶來後面「兩個不同階段的失敗」一節討論的後果:即使回應其後不向腳本公開,伺服器仍可能已執行簡單請求的操作。
常見錯誤
(對預檢要求驗證身份)
伺服器在處理 CORS 之前先做登入檢查,令每個沒有有效會話的請求都收到 401。瀏覽器發送預檢時不附帶網頁的 Cookie,所以預檢本身就收到 401。預檢必須得到成功狀態碼,瀏覽器因此視預檢為失敗,不會發送實際請求,儘管那個帶著 Cookie 的實際請求本來會被接受。應在驗證步驟之前,先回應帶有 Access-Control-Request-Method 的 OPTIONS 請求,再照常對實際請求進行驗證。
3. JSON 提交及其預檢
假設位於 https://app.example.test 的網頁向 https://api.example.test/notes 發送 POST。本例假設伺服器實作了下文所示的約定、用戶擁有一個符合條件的工作階段 cookie,而網頁已透過適當途徑取得一個應用程式專用的 CSRF 權杖。所示的權杖僅作說明之用。HTTPS、cookie 是否符合條件以及瀏覽器政策都是情境的一部分;程式碼中出現 credentials: "include",並不保證一定會附上 cookie。
async function createNote(title, csrfToken) {
const response = await fetch("https://api.example.test/notes", {
method: "POST",
credentials: "include",
headers: {
"Content-Type": "application/json",
"X-CSRF-Token": csrfToken
},
body: JSON.stringify({ title })
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
return response.json();
}
這裏的 application/json 並非 CORS 安全清單內的請求 Content-Type,而 X-CSRF-Token 亦不是安全清單內的請求標頭。假設沒有適用的已快取預檢許可,瀏覽器會先發送一個 OPTIONS 預檢請求。該請求會列明擬使用的方法及非安全清單標頭;它不會附帶實際的 JSON 內容或權杖的值。瀏覽器的預檢請求不會附帶該請求的跨來源憑證。以下 HTTP/1.1 風格的訊息省略了無關的標頭:
OPTIONS /notes HTTP/1.1
Host: api.example.test
Origin: https://app.example.test
Access-Control-Request-Method: POST
Access-Control-Request-Headers: content-type, x-csrf-token
伺服器以一個成功的回應允許這個組合,例如:
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.test
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Content-Type, X-CSRF-Token
Vary: Origin
允許的來源與網頁的來源完全相符。允許的方法包括 POST,允許的標頭亦包括所請求的兩個名稱;標頭名稱不區分大小寫。這裏需要 Access-Control-Allow-Credentials: true,因為隨後的 Fetch 使用憑證模式 include。對於憑證模式為 include 的請求,萬用字元 Access-Control-Allow-Origin: * 不能授權存取其回應。當伺服器根據請求的 Origin 來決定允許的來源時,Vary: Origin 便有其作用,使共用快取不會不加區分地把某個來源的回應重用於另一個來源。
成功的預檢只是允許瀏覽器發出實際請求;它本身並不是建立筆記的操作。在上述 cookie 假設下,一個簡化的實際交換如下:
POST /notes HTTP/1.1
Host: api.example.test
Origin: https://app.example.test
Cookie: sid=example-session
Content-Type: application/json
X-CSRF-Token: example-token
{"title":"Graph notes"}
HTTP/1.1 201 Created
Access-Control-Allow-Origin: https://app.example.test
Access-Control-Allow-Credentials: true
Content-Type: application/json
Vary: Origin
{"id":42,"title":"Graph notes"}
實際回應同樣需要適當的 CORS 標頭。根據本例的約定,201 及 JSON 內容表示已建立的筆記;response.ok 為真,而 response.json() 會解析回應內容。如果內容格式有誤,解析仍然可能失敗。對於一個 CORS 標頭允許公開的非成功 HTTP 回應,Fetch 通常會以一個回應物件完成(fulfill),而程式碼在檢查 response.ok 後會明確地拋出錯誤。相反,瀏覽器的 CORS 失敗在腳本看來是一個被拒絕(rejected)的 Fetch;腳本程式碼無法檢查被封鎖回應的狀態碼或內容。
4. 兩個不同階段的失敗
如果預檢未能通過 CORS 檢查,而又沒有已快取的許可允許該請求,瀏覽器便不會發送這個實際的 POST。檢查伺服器的 OPTIONS 回應及瀏覽器的網絡記錄,有助找出這類失敗的位置。相比之下,假設預檢成功,瀏覽器發送了 POST,伺服器建立了筆記,但實際的 201 回應遺漏了 Access-Control-Allow-Origin。即使操作可能已經完成,瀏覽器仍會阻止腳本讀取該回應。因此,Fetch 被拒絕並不能證明寫入操作沒有發生。除非應用程式具備合適的伺服器端冪等性(idempotency)約定,否則盲目重試可能會建立第二條筆記。
旁註
用三個問題排查 CORS
依次發問:請求有沒有發出?伺服器有沒有執行操作?腳本可否讀取回應?先在網絡記錄找 OPTIONS 請求;它缺席或失敗,便說明你正處於哪一個問題。
CORS 許可並不等於授權。伺服器仍須檢查工作階段,以及該用戶是否有權建立筆記。CORS 亦不能取代 CSRF 防禦:對於以 cookie 驗證身份的寫入操作,伺服器必須採用適合其部署環境的保護措施,例如驗證 CSRF 權杖,並配合合適的 cookie 及來源政策。有些跨來源請求無需預檢便可發送,所以單單拒絕 CORS 存取回應,並不是阻止不必要狀態變更的通用方法。
反例模式
前綴比對不是來源允許清單
有人聲稱:只要檢查 origin.startsWith("https://app.example.test") 就足以把該應用程式列入允許清單,然後伺服器連同 Access-Control-Allow-Credentials: true 回傳相符的 Origin。考慮由 https://app.example.test.evil.test 提供的網頁。它的來源字串以允許的文字開頭,檢查通過,伺服器於是回應 Access-Control-Allow-Origin: https://app.example.test.evil.test。若用戶的瀏覽器會帶上會話 Cookie,該網頁的腳本便可讀取 JSON 回應。較寬鬆的 origin.includes("example.test") 同樣會放行 https://example.test.evil.test。正確做法是把整個來源與固定集合比對,正如下面第二個解題實例中的 allowedOrigins.has(origin):來源是協定、主機和連接埠作為整體,而不是字串前綴。
5. 腳本可讀取哪些回應標頭
即使回應獲允許,腳本預設只能看到 CORS 安全清單內的回應標頭:Cache-Control、Content-Language、Content-Length、Content-Type、Expires、Last-Modified 和 Pragma。X-Total-Count 這類標頭會出現在瀏覽器的開發者工具中,但除非伺服器同時發送 Access-Control-Expose-Headers: X-Total-Count,否則 response.headers.get("X-Total-Count") 會回傳 null。這裏同樣顯示:網絡上看得見的內容,與腳本可以讀取的內容並不相同。因此,以自訂標頭報告分頁或頻率限制資訊的 API,必須明確列出這些標頭,否則瀏覽器腳本永遠看不到它們。
常見錯誤
(用 no-cors 消除錯誤)
開發者遇到 CORS 錯誤,便在調用中加上 mode: "no-cors"。fetch 的確不再被拒絕,但回應是不透明的:狀態碼為 0、內容為空,也讀不到任何標頭,所以腳本仍然甚麼也得不到。請求亦只限於簡單的方法和標頭。要修正錯誤,必須由伺服器送出合適的 CORS 標頭,而不是由調用端要求瀏覽器視而不見。
6. 解題實例
例題 7.1.3
(以萬用字元來源讀取公開 GET)
位於 https://app.example.test 的網頁在省略憑證的情況下執行以下程式碼。假設沒有重新導向,伺服器傳回帶有 JSON 的 200 及 Access-Control-Allow-Origin: *。
const response = await fetch("https://api.example.test/public-notes", { credentials: "omit" });
const notes = await response.json();
GET /public-notes HTTP/1.1
Host: api.example.test
Origin: https://app.example.test
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/json
[{"id":1,"title":"Public note"}]
方法是 GET,腳本沒有設定任何標頭,所以這是簡單請求:瀏覽器直接發送,並自行加上 Origin 標頭。由於憑證模式是 omit,萬用字元是可接受的,因此瀏覽器公開該 200 回應,response.json() 解析出陣列。這個請求無需預檢,回應的 Content-Type: application/json 也不會觸發預檢,因為這項決定只取決於請求的標頭和方法。這並不令數據變成機密;若伺服器遺漏該標頭,同一個調用在瀏覽器中便會失敗。
例題 7.1.4
(預檢列出的方法不足的 PUT)
網頁發送 fetch("https://api.example.test/notes/42", { method: "PUT", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ title: "Renamed" }) })。伺服器對瀏覽器預檢的回答如下。
OPTIONS /notes/42 HTTP/1.1
Host: api.example.test
Origin: https://app.example.test
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: content-type
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.test
Access-Control-Allow-Methods: GET, POST
Access-Control-Allow-Headers: Content-Type
Vary: Origin
PUT 不在安全清單的方法之內,application/json 亦不是安全清單的內容類型,所以必須預檢。瀏覽器把請求的方法 PUT 與 Access-Control-Allow-Methods: GET, POST 比對,發現沒有列出,便視預檢為失敗。實際的 PUT 從未發送,所以筆記沒有被改名;腳本的 fetch 以 TypeError 被拒絕,既讀不到狀態碼,也讀不到內容。只有 OPTIONS 請求到達了伺服器。修正要在伺服器進行:必須列出該方法及標頭。下面的中介軟件還會為來自獲允許來源的每個回應加上這些標頭,因為缺少標頭的錯誤回應同樣會被封鎖:
import express from "express";
const app = express();
const allowedOrigins = new Set(["https://app.example.test"]);
app.use((req, res, next) => {
const origin = req.get("Origin");
if (origin && allowedOrigins.has(origin)) {
res.set("Access-Control-Allow-Origin", origin);
res.set("Access-Control-Allow-Credentials", "true");
res.append("Vary", "Origin");
}
if (req.method === "OPTIONS" && req.get("Access-Control-Request-Method")) {
res.set("Access-Control-Allow-Methods", "GET, POST, PUT");
res.set("Access-Control-Allow-Headers", "Content-Type, X-CSRF-Token");
res.set("Access-Control-Max-Age", "600");
return res.status(204).end();
}
next();
});
app.use(express.json());
對不在集合內的來源,中介軟件不會設定 Access-Control-Allow-Origin 標頭,因此瀏覽器會封鎖該網頁的存取。這些標頭只是通知瀏覽器;路由處理函式仍須為每個請求進行身份驗證及授權。
例題 7.1.5
(寫入成功,回應卻被封鎖)
「JSON 提交與其預檢」一節的 POST 通過了預檢,但應用程式的實際回應如下,沒有任何 CORS 標頭。
HTTP/1.1 201 Created
Content-Type: application/json
{"id":43,"title":"Graph notes"}
瀏覽器已送出請求,所以伺服器執行了處理函式,並儲存了 id 為 43 的筆記。回應到達時,瀏覽器找不到與網頁來源相符的 Access-Control-Allow-Origin,便不向腳本公開該回應。腳本的 await fetch(...) 以 TypeError 被拒絕,程式碼無法檢視這個 201。看到錯誤而按下重試的用戶,可能會建立第二條筆記。要補救,伺服器必須為實際回應(包括錯誤回應)加上 CORS 標頭。可安全重試的設計會儲存由用戶端產生的請求識別碼,或提供讀取端點,讓用戶端能查明實際情況,而不是假設寫入失敗。
7. 練習
快速檢查
(為三個請求分類)
就下列每個跨來源請求,說明之前是否會有預檢。(a) fetch(url, { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" }, body: "a=1" })。(b) fetch(url, { method: "PUT" })。(c) fetch(url, { headers: { "X-Request-Id": "r1" } })。
解答
(a) 無需預檢:只帶表單內容類型的 POST 是簡單請求。(b) 會發送預檢,因為即使沒有標頭或內容,PUT 也不是 CORS 安全清單內的方法。(c) 會發送預檢:方法雖是 GET,但 X-Request-Id 不在安全清單內。請求 (a) 即使其後 CORS 禁止腳本讀取回應,仍可到達伺服器並改變狀態。
快速檢查
(萬用字元與憑證)
網頁調用 fetch(url, { credentials: "include" })。回應帶有 Access-Control-Allow-Origin: * 及 Access-Control-Allow-Credentials: true。腳本能取得回應嗎?伺服器應如何改為回應?
解答
不能。憑證模式為 include 時,萬用字元的 Access-Control-Allow-Origin 不能授權讀取回應,而 Access-Control-Allow-Credentials: true 也無法補救。瀏覽器會封鎖回應,fetch 被拒絕。伺服器應把請求的 Origin 與允許清單比對,原樣回傳相符的來源,保留 Access-Control-Allow-Credentials: true,並加上 Vary: Origin,讓快取把不同來源的回應分開。
快速檢查
(消失的標頭)
開發者工具顯示獲允許的跨來源回應帶有 X-Total-Count: 57,但 response.headers.get("X-Total-Count") 回傳 null。請解釋並修正。
解答
除非伺服器公開其他標頭,腳本只能讀取 CORS 安全清單內的回應標頭,而 X-Total-Count 不在其中。伺服器須在回應加上 Access-Control-Expose-Headers: X-Total-Count,腳本才能讀取該值。這個標頭並非沒有出現在網絡流量中,只是對腳本隱藏。
快速檢查
(把 CORS 當作安全牆)
開發者說:「我們的 API 只為 https://app.example.test 發送 CORS 標頭,所以其他網站或程式都無法調用它。」請指出兩個錯誤。
解答
第一,CORS 是由瀏覽器對網頁內容執行的。命令列用戶端、另一部伺服器上的腳本或被修改的瀏覽器都不理會它,可以發送任何請求。第二,即使在瀏覽器內,簡單請求無需預檢便會發送,CORS 只決定調用的腳本能否讀取回應,並不決定伺服器有沒有處理請求。所以保護必須靠伺服器端的身份驗證、授權及 CSRF 防禦。
快速檢查
(DELETE 與只列兩種方法的預檢)
DELETE /notes/42 的預檢回傳 204,帶有正確的 Access-Control-Allow-Origin 及 Access-Control-Allow-Methods: GET, POST。哪些請求會到達伺服器?腳本觀察到甚麼?必須修改甚麼?
解答
只有 OPTIONS 預檢到達伺服器。瀏覽器發現沒有列出 DELETE,視預檢為失敗,從不發送 DELETE,所以筆記仍然存在。腳本觀察到被拒絕的 fetch,沒有狀態碼或內容。伺服器必須把 DELETE 加入 Access-Control-Allow-Methods。這與第三個實例中被封鎖的 201 不同,那次寫入確實已經發生。