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

Javascript, 網站相關

JWT Refresh Token Rotation 怎麼做?雙權杖輪替、重複使用偵測與登出撤銷

JWT Refresh Token Rotation 怎麼做?雙權杖輪替、重複使用偵測與登出撤銷 特色圖片

Access Token 放記憶體、Refresh Token 放 HttpOnly Cookie 之後,還有兩件事要處理:Refresh Token 被偷了怎麼發現,以及使用者按下登出時,已經發出去的 Token 怎麼失效。本文用 Refresh Token Rotation(輪替)加上重複使用偵測處理前者,用 Token 家族撤銷與 jti 黑名單處理後者。

本文是 JWT 存放系列第 3 篇。Token 該放記憶體還是 Cookie、Refresh Cookie 的 HttpOnly/Secure/SameSite 設定,見第 1 篇 〈JWT 存放位置怎麼選?LocalStorage、Cookie 與記憶體的資安比較〉;前端與 API 不同網域時的 SameSite、CORS 與 CSRF Token,見第 2 篇 〈跨網域 Cookie 設定:SameSite、CORS credentials 與 CSRF 防禦〉。

要直接看後端與前端程式碼,可前往 #examples。

一、 雙權杖的分工:Access Token 短效,Refresh Token 要能撤銷

RFC 6749 對 Refresh Token 的定義是「用來取得 Access Token 的憑證」:Access Token 失效或過期時,用它換一個新的。OAuth 2.0 安全最佳實務 RFC 9700(2025 年 1 月發布)說明了這樣分工的好處:伺服器可以把 Access Token 的效期設得很短、權限設得很小,降低 Access Token 外洩的影響。

代價是 Refresh Token 變成攻擊者最想要的東西。RFC 9700 §4.14.1 指出,攻擊者只要偷到並成功重送 Refresh Token,就能一直換出新的 Access Token。所以兩種 Token 的管理方式不同:

Access TokenRefresh Token
本文範本的格式簽章 JWT,15 分鐘32 位元組亂數,7 天
伺服器怎麼驗證驗簽章與 exp、iss,再查撤銷清單查伺服器端的紀錄
怎麼讓它提前失效jti 黑名單或版本號(第三節)刪除或撤銷紀錄

Refresh Token 只有伺服器自己會讀,又要能隨時撤銷,伺服器本來就得保存它的狀態,所以範本直接用亂數字串,資料庫只存它的 SHA-256 雜湊值,資料庫外洩時拿不到可用的 Token。

二、 Refresh Token Rotation 與重複使用偵測

RFC 6749 §6 允許伺服器在換發時發一個新的 Refresh Token,此時用戶端必須丟掉舊的、改用新的,伺服器也可以撤銷舊的。RFC 9700 §4.14.2 把這個做法寫成 Refresh Token Rotation:每次換發 Access Token 都一併發新的 Refresh Token,舊的作廢,但伺服器要保留新舊 Token 之間的關係。

保留關係的用途是偵測重複使用。Refresh Token 被偷之後,攻擊者與合法使用者總有一方會送出已經作廢的舊 Token,伺服器一看到就知道外洩了。伺服器分不出是哪一方送的,所以把同一串(同一個 Token 家族)目前有效的 Refresh Token 一起撤銷;攻擊被擋下,代價是合法使用者要重新登入。

情境第一個送出之後送出結果
攻擊者拿舊 Token 重送使用者換到新 Token攻擊者送舊 Token偵測到重複使用,家族撤銷,使用者手上的新 Token 也失效
攻擊者先用偷到的 Token攻擊者換到新 Token使用者送同一個舊 Token偵測到重複使用,家族撤銷,攻擊者換到的新 Token 失效

RFC 9700 §2.2.2 要求公開用戶端(public client)的 Refresh Token 必須綁定發送者,或使用 Refresh Token Rotation。在瀏覽器執行的 SPA 在 RFC 6749 的分類中屬於公開用戶端,無法安全保存密鑰;自建登入系統雖然不是 OAuth,Refresh Cookie 的處境相同,可以沿用同樣的設計。

RFC 9700 也建議:Refresh Token 一段時間沒被用來換發就應該過期;伺服器可以在密碼變更或登出等安全事件時自動撤銷 Refresh Token。

三、 登出時要做的三件事:清 Cookie 不等於 Token 失效

OWASP Session Management Cheat Sheet 要求登出時至少要在伺服器端讓 Session 失效,並提醒只刪除 Cookie 無法讓被偷走的副本失效。JWT 也一樣:前端刪掉 Token,伺服器沒有任何紀錄,簽章與 exp 仍然有效的 Access Token 照樣能用。所以登出 API 要做三件事:

  1. 撤銷 Refresh Token 家族:之後拿這個家族的任何 Refresh Token 來換發都會失敗。
  2. 把 Access Token 的 jti 放進黑名單:RFC 7519 定義 jti(JWT ID)是 JWT 的唯一識別碼,可用來防止 JWT 被重送。OWASP JWT Cheat Sheet 建議黑名單以 jti 加上 iss 當鍵值,並且不要拿整串 JWT 或它的雜湊當鍵值:攻擊者可能把已撤銷的 JWT 改成另一種仍能通過簽章驗證的寫法,繞過黑名單。黑名單項目只要保留到該 Token 的 exp,過期後簽章驗證本來就會拒絕。
  3. 清除 Refresh Cookie:Express 的 res.clearCookie() 要帶和 res.cookie() 相同的選項(maxAge、expires 除外),path 不同時瀏覽器不會刪除。範本把兩邊共用同一個 refreshCookieOptions 物件。

使用者改密碼或懷疑帳號外洩時,要讓所有裝置一起登出。逐一把每台裝置的 jti 放進黑名單並不實際,範本改用版本號:每個使用者存一個數字放進 Access Token 的 ver 宣告,登出所有裝置時把數字加 1,舊版本號的 Access Token 全部不再接受,同時撤銷這個使用者所有的 Token 家族。

四、 實作範本:輪替、重複使用偵測與登出

範本一:Express API(Refresh Token Rotation+登出撤銷)

以下程式使用 Express 5、cookie-parser 與 jsonwebtoken 9。HTTPS 由前方的反向代理處理;前端與 API 同源。

import crypto from 'node:crypto';
import express from 'express';
import cookieParser from 'cookie-parser';
import jwt from 'jsonwebtoken';

const app = express();
app.use(express.json());
app.use(cookieParser());

const ACCESS_SECRET = process.env.ACCESS_SECRET; // 由環境變數提供,不寫進程式碼
const ISSUER = 'https://api.example.com';
const ACCESS_TTL_SEC = 15 * 60;
const REFRESH_TTL_MS = 7 * 24 * 60 * 60 * 1000;
const REFRESH_COOKIE = 'refreshToken';
// Path 涵蓋 refresh、logout、logout-all 三支,其他 API 收不到這個 Cookie
const refreshCookieOptions = { httpOnly: true, secure: true, sameSite: 'lax', path: '/api/auth' };

// 示範用的記憶體儲存,正式環境改用資料庫或 Redis
const refreshTokens = new Map(); // SHA-256(Refresh Token) → { familyId, userId, used, expiresAt }
const families = new Map(); // familyId → { userId, revoked }
const deniedAccess = new Map(); // `${iss}|${jti}` → exp(秒)
const tokenVersions = new Map(); // userId → 版本號,登出所有裝置時加 1

const hash = (value) => crypto.createHash('sha256').update(value).digest('hex');
const verifyAccess = (token) =>
  jwt.verify(token, ACCESS_SECRET, { algorithms: ['HS256'], issuer: ISSUER });
const bearer = (req) => (req.get('Authorization') ?? '').replace(/^Bearer /, '');

function sendTokens(res, userId, familyId) {
  const refreshToken = crypto.randomBytes(32).toString('base64url');
  refreshTokens.set(hash(refreshToken), {
    familyId, userId, used: false, expiresAt: Date.now() + REFRESH_TTL_MS,
  });
  res.cookie(REFRESH_COOKIE, refreshToken, { ...refreshCookieOptions, maxAge: REFRESH_TTL_MS });

  const accessToken = jwt.sign({ ver: tokenVersions.get(userId) ?? 0 }, ACCESS_SECRET, {
    algorithm: 'HS256', expiresIn: ACCESS_TTL_SEC, issuer: ISSUER,
    subject: userId, jwtid: crypto.randomUUID(),
  });
  res.json({ accessToken, expiresIn: ACCESS_TTL_SEC });
}

function rejectRefresh(res, error) {
  res.clearCookie(REFRESH_COOKIE, refreshCookieOptions);
  return res.status(401).json({ error });
}

function authenticate(req, res, next) {
  try {
    const claims = verifyAccess(bearer(req));
    const revoked = deniedAccess.has(`${claims.iss}|${claims.jti}`)
      || claims.ver !== (tokenVersions.get(claims.sub) ?? 0);
    if (revoked) return res.status(401).json({ error: 'token_revoked' });
    req.auth = claims;
    next();
  } catch {
    res.status(401).json({ error: 'invalid_token' });
  }
}

app.post('/api/auth/login', (req, res) => {
  const userId = 'usr_8892'; // 省略帳號密碼驗證
  const familyId = crypto.randomUUID(); // 每次登入開一個新的 Token 家族
  families.set(familyId, { userId, revoked: false });
  sendTokens(res, userId, familyId);
});

app.post('/api/auth/refresh', (req, res) => {
  const token = req.cookies[REFRESH_COOKIE];
  const record = token && refreshTokens.get(hash(token));
  const family = record && families.get(record.familyId);
  if (!family || family.revoked || record.expiresAt <= Date.now()) {
    return rejectRefresh(res, 'invalid_refresh_token');
  }
  if (record.used) {
    family.revoked = true; // 舊 Token 被重複使用:撤銷整個家族
    return rejectRefresh(res, 'refresh_token_reused');
  }
  record.used = true; // 標記為已使用但保留紀錄,之後才認得出重複使用
  sendTokens(res, record.userId, record.familyId);
});

app.post('/api/auth/logout', (req, res) => {
  const token = req.cookies[REFRESH_COOKIE];
  const record = token && refreshTokens.get(hash(token));
  if (record) families.get(record.familyId).revoked = true;
  try {
    const { iss, jti, exp } = verifyAccess(bearer(req));
    deniedAccess.set(`${iss}|${jti}`, exp); // 留到 exp 為止
  } catch {} // 沒帶或已過期的 Access Token 不必進黑名單
  res.clearCookie(REFRESH_COOKIE, refreshCookieOptions);
  res.sendStatus(204);
});

// 改密碼、懷疑帳號外洩時:讓這個使用者所有裝置的 Token 失效
app.post('/api/auth/logout-all', authenticate, (req, res) => {
  const userId = req.auth.sub;
  tokenVersions.set(userId, (tokenVersions.get(userId) ?? 0) + 1);
  for (const family of families.values()) {
    if (family.userId === userId) family.revoked = true;
  }
  res.clearCookie(REFRESH_COOKIE, refreshCookieOptions);
  res.sendStatus(204);
});

app.get('/api/me', authenticate, (req, res) => {
  res.json({ userId: req.auth.sub });
});

// 定期清掉已過期的黑名單與 Refresh Token 紀錄
setInterval(() => {
  const nowSec = Date.now() / 1000;
  for (const [key, exp] of deniedAccess) if (exp <= nowSec) deniedAccess.delete(key);
  for (const [key, r] of refreshTokens) if (r.expiresAt <= Date.now()) refreshTokens.delete(key);
}, 60_000).unref();

app.listen(process.env.PORT ?? 4000);

jwt.verify() 明確指定 algorithms: ['HS256'],標頭改成 alg: none 的 Token 會被拒絕(回 invalid_token)。第 1 篇的 Refresh Cookie Path 是 /api/auth/refresh,這裡改成 /api/auth,因為登出 API 也要收到這個 Cookie 才知道要撤銷哪個家族。

以 Node.js 22 對範本一送出請求的結果:

Node.js 22、Windows 11 對範本一送出請求的結果:正常輪替回 200;舊 Refresh Token 重送回 401 refresh_token_reused,同家族的新 Token 也失效;登出後舊 Access Token 回 401 token_revoked;沒呼叫登出 API 時舊 Access Token 仍回 200;登出所有裝置後另一台裝置的 Token 失效

範本二:前端換發與登出(single-flight+Web Locks)

Access Token 只放記憶體。換發函式在同一分頁內共用同一個請求,跨分頁再用 Web Locks API 排隊(原因見 Q1)。遇到 401 自動換發並重送原請求的封裝,見第 1 篇的範本二。

let accessToken = null; // 只放記憶體
let refreshing = null;

export const getAccessToken = () => accessToken;

export async function login(username, password) {
  const res = await fetch('/api/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ username, password }),
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  ({ accessToken } = await res.json());
}

// 同一分頁的多個呼叫共用一次換發;Web Locks 讓同源的其他分頁排隊
export function refreshAccessToken() {
  refreshing ??= navigator.locks
    .request('auth-refresh', async () => {
      const res = await fetch('/api/auth/refresh', { method: 'POST' });
      accessToken = res.ok ? (await res.json()).accessToken : null;
      return accessToken;
    })
    .finally(() => {
      refreshing = null;
    });
  return refreshing;
}

export async function logout() {
  await fetch('/api/auth/logout', {
    method: 'POST',
    headers: accessToken ? { Authorization: `Bearer ${accessToken}` } : {},
  });
  accessToken = null;
}
Chrome 156 無頭模式、Windows 11 執行範本一與範本二的結果:同分頁 3 個呼叫只送 1 次 refresh;直接同時送 2 個 refresh 時第 2 個被判成重複使用;兩個分頁經 Web Locks 依序換發都成功,不排隊時其中一個被判成重複使用;登出後 Cookie 清除、舊 Access Token 回 401

五、 常見問題與排錯(Q&A)

Q1:啟用輪替後,使用者常常莫名被登出?

最常見的原因是同時送出多個換發請求。頁面同時有好幾支 API 拿到 401、各自去換發時,這些請求帶的是同一個 Refresh Cookie:第一個換發成功,舊 Token 就被標成已使用,第二個送到時被判成重複使用,整個家族撤銷(上方第二張圖的兩個對照列就是這個情況)。

同一分頁內用一個共用的 Promise 讓所有呼叫等同一次換發(範本二的 refreshing)。多個分頁共用同一個 Cookie,但記憶體各自獨立,所以再用 Web Locks API:同源的分頁同一時間只有一個能拿到同名的鎖,後面的分頁等前一個換發完成、Cookie 已更新,才用新的 Cookie 送出。

Q2:黑名單會不會越來越大?一定要做嗎?

黑名單只需要保存「已登出、但還沒過期」的 Access Token,項目存到 exp 就刪除(範本的 setInterval),大小上限約等於 Access Token 效期內的登出次數。多台伺服器時要放在共享儲存(例如 Redis),每台都查同一份。

不想維護黑名單時,OWASP JWT Cheat Sheet 列出的替代做法之一是縮短 JWT 的效期:登出後撤銷 Refresh Token 家族,舊的 Access Token 最多再用到過期為止。能不能接受這段空窗,依服務的風險決定。

Q3:使用者改了密碼,舊裝置上的 Token 怎麼處理?

RFC 9700 §4.14.2 列出密碼變更是可以自動撤銷 Refresh Token 的安全事件;OWASP Session Management Cheat Sheet 也把密碼變更列為權限等級改變的情境,要求重新產生 Session ID、舊的作廢。範本的做法是改密碼後呼叫 /api/auth/logout-all 的同一段邏輯:版本號加 1、撤銷這個使用者所有的 Token 家族,再為目前這台裝置重新登入發新 Token。

參考資料與延伸閱讀

發佈留言