前後端分離後,跨網域 Cookie 常出現「登入成功、下一支 API 卻是未登入」。要讓 Cookie 跨來源送出,前端的 credentials、伺服器的 CORS 標頭與 Cookie 的 SameSite 都要對;Cookie 送得出去後,CSRF 防禦也要補上。
本文是 JWT 存放系列第 2 篇。Token 該放記憶體還是 Cookie,見第 1 篇 〈JWT 存放位置怎麼選?LocalStorage、Cookie 與記憶體的資安比較〉;HttpOnly 的基本設定見 〈HTTPOnly Cookie 怎麼設定?新手工程師常見 XSS 防禦實作〉;CSRF 攻擊流程見 〈CSRF 跨站請求偽造攻擊原理與 Anti-CSRF Token 防禦實作〉。
一、 跨來源不等於跨站:先判斷你的部署屬於哪一種
CORS 看的是「來源(origin)」:協定、主機、連接埠三者相同才算同源。SameSite 看的是「站(site)」:由可註冊網域(registrable domain,也就是 Public Suffix List 上的後綴再加左邊一段)決定,連接埠不算在內;處理 SameSite Cookie 時還會比對協定(schemeful same-site),所以 http:// 與 https:// 算不同站。
下表四種都是跨來源,都要設 CORS;差別在是否同站:
| 前端 → API | 同站? | SameSite=Lax 的 Cookie 會送? |
|---|---|---|
https://app.example.com → https://api.example.com | 是 | 會 |
http://localhost:5173 → http://localhost:4000 | 是(連接埠不影響) | 會 |
https://frontend.example.org → https://api.example.com | 否 | 不會,要改 SameSite=None; Secure |
http://example.com → https://example.com | 否(協定不同) | 不會 |
前端與 API 在同一個可註冊網域底下(例如 app. 與 api. 子網域)時,SameSite=Lax 就能用。分屬不同站時,Cookie 對前端頁面而言是第三方 Cookie,除了要設 SameSite=None; Secure,還會受瀏覽器的第三方 Cookie 政策影響:Safari 預設啟用追蹤防護、Firefox 的 Total Cookie Protection 會把第三方 Cookie 依網站分開存放,Chrome 預設不封鎖。能選擇部署方式時,讓 API 與前端同站最單純。
二、 Cookie 要跨來源送出的三個條件
- 前端要求帶憑證:
fetch()的credentials預設是same-origin,跨來源請求不會送 Cookie,回應的Set-Cookie也不會被採用,要明確設成'include'。XMLHttpRequest用withCredentials = true;Axios 用withCredentials: true(見範本三)。 - 伺服器允許帶憑證:CORS 標頭的設定方式與
No 'Access-Control-Allow-Origin' header等錯誤排查,可前往 〈瀏覽器 Same-Origin Policy 同源政策與跨來源限制原理〉 觀看。帶 Cookie 時要特別注意:Allow-Headers、Allow-Methods同樣不能用*;缺少這些標頭時 Cookie 其實已送出,只是瀏覽器不把回應交給 JavaScript;Access-Control-Allow-Origin是*時,回應的Set-Cookie也不生效。Preflight(OPTIONS)不帶 Cookie,但回應同樣要有Access-Control-Allow-Credentials: true。回傳的 Origin 依請求而變時,加上Vary: Origin。 - Cookie 的 SameSite 允許這種請求:同站請求三種值都會送;跨站請求只有
SameSite=None; Secure會送(Lax另外允許頂層導覽的 GET)。

三、 SameSite 的 Strict、Lax、None 怎麼選
Strict與Lax:兩者在外部連結導入、跨站 POST 時的差異與取捨,可前往 〈CSRF 跨站請求偽造攻擊原理與 Anti-CSRF Token 防禦實作〉 觀看。前端與 API 同站時,選Lax即可。None:同站、跨站都送,而且必須同時設Secure;沒有Secure的SameSite=NoneCookie 會被瀏覽器忽略,不會寫入。前端與 API 不同站時才需要。
SameSite 只是 CSRF 的縱深防禦。它以可註冊網域判斷,同一網域下的其他子網域(例如 blog.example.com)發出的請求屬於同站,Lax 甚至 Strict 的 Cookie 都會帶上。會改變資料的 API 仍要有 CSRF Token。
四、 實作範本:CORS 白名單、HttpOnly Cookie 與 CSRF Token
以下範本採 OWASP 建議的 Signed Double-Submit Cookie:CSRF Token 由亂數加上「以 Session ID 與亂數計算的 HMAC」組成,綁定目前的登入 Session。前端讀不到另一台主機(API)設下的 Cookie,所以 Token 由回應內容交給前端,放在記憶體,送出時放進自訂標頭 X-CSRF-Token。自訂標頭會觸發 Preflight,不在白名單的來源送不出這個標頭。
範本一:Express API(CORS 白名單+__Host- Cookie+CSRF 驗證)
以下程式使用 Express 5 與 cookie-parser;HTTPS 由前方的反向代理處理。
import crypto from 'node:crypto';
import express from 'express';
import cookieParser from 'cookie-parser';
const app = express();
const ALLOWED_ORIGINS = new Set(
(process.env.ALLOWED_ORIGINS ?? 'https://app.example.com').split(',')
);
// 前端與 API 不同站(例如 frontend.example.org → api.example.com)才改用 None
const SAME_SITE = process.env.CROSS_SITE_FRONTEND === '1' ? 'none' : 'lax';
const CSRF_SECRET = process.env.CSRF_SECRET; // 由環境變數提供,不寫進程式碼
const sessions = new Map(); // 示範用,正式環境改用 Redis 或資料庫
app.use(express.json());
app.use(cookieParser());
// CORS:只回應白名單內的 Origin,帶憑證時不能用 *
app.use((req, res, next) => {
const origin = req.headers.origin;
if (origin && ALLOWED_ORIGINS.has(origin)) {
res.set({
'Access-Control-Allow-Origin': origin,
'Access-Control-Allow-Credentials': 'true',
Vary: 'Origin',
});
if (req.method === 'OPTIONS') {
res.set({
'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE',
'Access-Control-Allow-Headers': 'Content-Type, X-CSRF-Token',
});
return res.sendStatus(204);
}
}
next();
});
const cookieOptions = { httpOnly: true, secure: true, sameSite: SAME_SITE, path: '/' };
function signCsrf(sessionId, random) {
const message = `${sessionId.length}:${sessionId}${random.length}:${random}`;
return crypto.createHmac('sha256', CSRF_SECRET).update(message).digest('hex');
}
function issueCsrfToken(res, sessionId) {
const random = crypto.randomBytes(16).toString('hex');
const token = `${random}.${signCsrf(sessionId, random)}`;
res.cookie('__Host-csrf', token, cookieOptions);
return token;
}
function requireSession(req, res, next) {
const sessionId = req.cookies['__Host-session'];
if (!sessionId || !sessions.has(sessionId)) {
return res.status(401).json({ error: 'unauthenticated' });
}
req.sessionId = sessionId;
next();
}
function verifyCsrf(req, res, next) {
const header = req.get('X-CSRF-Token') ?? '';
const [random, mac] = header.split('.');
if (!random || !mac || header !== req.cookies['__Host-csrf']) {
return res.status(403).json({ error: 'csrf' });
}
const expected = Buffer.from(signCsrf(req.sessionId, random));
const actual = Buffer.from(mac);
if (expected.length !== actual.length || !crypto.timingSafeEqual(expected, actual)) {
return res.status(403).json({ error: 'csrf' });
}
next();
}
app.post('/api/login', (req, res) => {
// 省略帳號密碼驗證,只示範登入成功後發出的 Cookie 與 CSRF Token
const sessionId = crypto.randomBytes(32).toString('hex');
sessions.set(sessionId, { user: req.body?.username });
res.cookie('__Host-session', sessionId, cookieOptions);
res.json({ csrfToken: issueCsrfToken(res, sessionId) });
});
// 重新整理頁面後,前端用這支取回新的 CSRF Token
app.get('/api/csrf', requireSession, (req, res) => {
res.json({ csrfToken: issueCsrfToken(res, req.sessionId) });
});
app.get('/api/me', requireSession, (req, res) => {
res.json({ user: sessions.get(req.sessionId).user });
});
app.post('/api/transfer', requireSession, verifyCsrf, (req, res) => {
res.json({ ok: true, amount: req.body.amount });
});
app.listen(process.env.PORT ?? 4000);
範本二:前端 fetch 封裝(credentials: 'include'+X-CSRF-Token)
const API_BASE = 'https://api.example.com';
let csrfToken = null; // 只放記憶體,不寫入 localStorage
async function apiFetch(path, { method = 'GET', body } = {}) {
const headers = {};
if (body) headers['Content-Type'] = 'application/json';
if (method !== 'GET' && csrfToken) headers['X-CSRF-Token'] = csrfToken;
const res = await fetch(API_BASE + path, {
method,
headers,
credentials: 'include', // 跨來源請求要明確帶上 Cookie
body: body ? JSON.stringify(body) : undefined,
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
return res.json();
}
export async function login(username, password) {
({ csrfToken } = await apiFetch('/api/login', { method: 'POST', body: { username, password } }));
}
export async function restoreCsrfToken() {
({ csrfToken } = await apiFetch('/api/csrf'));
}
export const getProfile = () => apiFetch('/api/me');
export const transfer = (amount) => apiFetch('/api/transfer', { method: 'POST', body: { amount } });
範本三:Axios 版(withCredentials: true)
import axios from 'axios';
const api = axios.create({
baseURL: 'https://api.example.com',
withCredentials: true, // 等同 fetch 的 credentials: 'include'
});
function setCsrfToken({ data }) {
// 只放記憶體,之後的請求都帶 X-CSRF-Token
api.defaults.headers.common['X-CSRF-Token'] = data.csrfToken;
}
export const login = (username, password) =>
api.post('/api/login', { username, password }).then(setCsrfToken);
export const restoreCsrfToken = () => api.get('/api/csrf').then(setCsrfToken);
export const getProfile = () => api.get('/api/me').then((res) => res.data);
export const transfer = (amount) => api.post('/api/transfer', { amount }).then((res) => res.data);
Axios 的 withCredentials 只管帶不帶 Cookie,不會加內建的 XSRF 標頭(跨來源要另設 withXSRFToken: true);這裡 Token 取自回應,直接設在 defaults.headers。
範本在 app.example.com → api.example.com 的同站部署下執行的結果:登入時先送 Preflight(OPTIONS 204),再送 POST,回應寫入 __Host-session 與 __Host-csrf;transfer() 帶 X-CSRF-Token 回 200,帶 Cookie 但沒有這個標頭回 403。重新整理頁面後記憶體裡的 Token 消失,直接送出會是 403,先呼叫 restoreCsrfToken() 再送就恢復正常。
攻擊情境的結果:同站子網域 blog.example.com 的表單 POST 會帶上 Lax Cookie,被 CSRF 驗證擋下(403);跨站的 evil.example.net 表單 POST,在 Lax 時 Cookie 不送(401),改成 None 後 Cookie 會送,同樣被擋(403);不在白名單的來源用 fetch 加自訂標頭,Preflight 回應沒有 Access-Control-Allow-Origin,正式的 POST 根本沒有送出。

只比對「標頭與 Cookie 相同」、沒有簽章的 Naive Double-Submit Cookie,OWASP 不建議使用:能在其他子網域寫入 Cookie 的攻擊者,可以自己種一組相同的值。範本把 Token 綁定 Session 並用 crypto.timingSafeEqual 比對 HMAC,就是為了避開這個問題。
五、 跨子網域共用 Cookie:Domain 屬性與 Cookie Tossing
為了讓 app.example.com 與 api.example.com 共用 Cookie,常有人設定 Domain=.example.com。設定 Domain 為父網域(前導點會被忽略,效果與 example.com 相同)後,父網域與所有子網域(包括安全層級較低或由其他團隊營運的 blog.example.com、user-content.example.com)的請求都會帶上這個 Cookie;沒有 HttpOnly 時,子網域頁面的 JavaScript 也讀得到。反過來,子網域本來就能設定 Domain=example.com 的同名 Cookie,覆寫其他子網域使用的值(Cookie Tossing)。
Session Cookie 只需要送給 API,所以不設 Domain,讓它成為只回傳給設定它那台主機的 host-only Cookie。再加上 __Host- 前綴,瀏覽器會要求這個 Cookie 必須 Secure、Path=/ 且不能有 Domain,其他子網域就無法用 Domain=example.com 寫入同名 Cookie 覆寫。範本一的兩個 Cookie 都是這樣設定。
上方第二張圖下半部:blog.example.com 以 document.cookie 寫入 Domain=example.com 的 __Host-csrf 被拒絕;沒有前綴的 csrf 寫入成功,之後也會送到 api.example.com。
六、 常見問題與排錯(Q&A)
Q1:登入 API 回了 200,下一支 API 卻是 401?
依序檢查:前端請求有沒有 credentials: 'include'(登入那一支也要,否則回應的 Set-Cookie 不會被採用);回應的 Access-Control-Allow-Origin 是不是明確來源、有沒有 Access-Control-Allow-Credentials: true;SameSite=None 有沒有同時設 Secure;前端與 API 若不同站,Cookie 是不是還停在 Lax(上方第一張圖第 3 列就是這個情況),或被瀏覽器的第三方 Cookie 政策擋下。
Q2:手機 App 與網頁共用同一組 API,要用 Cookie 還是 Authorization 標頭?
常見做法是雙軌:網頁用本文的 HttpOnly Cookie+CSRF Token;原生 App 由登入 API 取得 Token,存在系統安全儲存區,每次請求自己放進 Authorization: Bearer <token>。iOS 用 Keychain Services;Android 原本常用的 Jetpack EncryptedSharedPreferences 已在 security-crypto 1.1.0 全部標為棄用,官方建議改用平台 API 與 Android Keystore。伺服器端兩種來源分開處理,Cookie 驗證的請求維持 CSRF 檢查。
Q3:使用者登出時,Cookie 裡的 JWT 要怎麼失效?
登出清除 Cookie、Token 撤銷與 Refresh Token 輪替,在 JWT 存放系列第 3 篇 說明。
參考資料與延伸閱讀
- MDN: Set-Cookie header
- MDN: Site(可註冊網域與 schemeful same-site)
- MDN: Cross-Origin Resource Sharing (CORS)
- MDN: Access-Control-Allow-Origin
- MDN: RequestInit(fetch 的 credentials 選項)
- MDN: Third-party cookies
- draft-ietf-httpbis-rfc6265bis-22: Cookies: HTTP State Management Mechanism
- RFC 6265 §8.6: Weak Integrity
- OWASP Cross-Site Request Forgery Prevention Cheat Sheet
- Axios: Request Config
- Axios README(GitHub)
- Apple Developer: Keychain services
- Android Developers: Security(security-crypto 版本紀錄)
- JWT 存放位置怎麼選?LocalStorage、Cookie 與記憶體的資安比較
- CSRF 跨站請求偽造攻擊原理與 Anti-CSRF Token 防禦實作
- CORS 錯誤是什麼? 如何解決本地端跨域請求 CORS Error
- 瀏覽器 Same-Origin Policy 同源政策與跨來源限制原理
- JWT Refresh Token Rotation 怎麼做?雙權杖輪替、重複使用偵測與登出撤銷
發佈留言