紀錄工作經驗、相關知識,解決技術相關問題。

Javascript, 新手 Jamp Holes, 網站相關

跨網域 Cookie 設定:SameSite、CORS credentials 與 CSRF 防禦

跨網域 Cookie 設定:SameSite、CORS credentials 與 CSRF 防禦 特色圖片

前後端分離後,跨網域 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 要跨來源送出的三個條件

  1. 前端要求帶憑證:fetch() 的 credentials 預設是 same-origin,跨來源請求不會送 Cookie,回應的 Set-Cookie 也不會被採用,要明確設成 'include'。XMLHttpRequest 用 withCredentials = true;Axios 用 withCredentials: true(見範本三)。
  2. 伺服器允許帶憑證: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。
  3. Cookie 的 SameSite 允許這種請求:同站請求三種值都會送;跨站請求只有 SameSite=None; Secure 會送(Lax 另外允許頂層導覽的 GET)。
Chrome 156 無頭模式、Windows 11 執行範本一與範本二的結果:app.example.com 與 api.example.com 同站,SameSite=Lax 的 Cookie 會送出;未設 credentials 時不送;frontend.example.org 跨站時只有 SameSite=None; Secure 的 Cookie 會送出

三、 SameSite 的 Strict、Lax、None 怎麼選

  • Strict 與 Lax:兩者在外部連結導入、跨站 POST 時的差異與取捨,可前往 〈CSRF 跨站請求偽造攻擊原理與 Anti-CSRF Token 防禦實作〉 觀看。前端與 API 同站時,選 Lax 即可。
  • None:同站、跨站都送,而且必須同時設 Secure;沒有 Secure 的 SameSite=None Cookie 會被瀏覽器忽略,不會寫入。前端與 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 根本沒有送出。

Chrome 156 無頭模式、Windows 11 執行範本一的結果:同站子網域與跨站的表單 POST 被 CSRF 驗證擋下或沒帶 Cookie,跨站 fetch 帶自訂標頭時 Preflight 失敗;blog.example.com 寫入 Domain=example.com 的 __Host-csrf 被拒絕,無前綴的 csrf 寫入成功

只比對「標頭與 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 篇 說明。

參考資料與延伸閱讀

發佈留言