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

Javascript, 網站相關

JWT 存放位置怎麼選?LocalStorage、Cookie 與記憶體的資安比較

JWT 存放位置怎麼選?LocalStorage、Cookie 與記憶體的資安比較 特色圖片

維持登入狀態時,開發者要決定 Access Token 與 Refresh Token 放在哪裡。JWT 存放位置若未妥善規劃,網站可能遭受跨站腳本攻擊(XSS)或跨站請求偽造(CSRF)。

本文聚焦 JWT 存放策略與資安邊界;三種儲存方式的基本用法與使用場景,可先看 〈前端資料儲存 Cookie、localStorage、sessionStorage 使用場景、限制、差異〉;HttpOnly Cookie 的基本設定見 〈HTTPOnly Cookie 怎麼設定?新手工程師常見 XSS 防禦實作〉。CSRF 攻擊流程見 〈CSRF 跨站請求偽造攻擊原理與 Anti-CSRF Token 防禦實作〉,請求動詞的資安特性見 〈淺談 HTTP 請求方法 (HTTP Request Methods):GET、POST、PUT、DELETE 基礎概念與 Fetch 入門〉。

要快速查看各種場景的 Token 存放範本,可直接前往 #examples。


一、 核心速查與常見瓶頸對照

1. 常見錯誤寫法的工程瓶頸

許多前端開發專案為了實作方便,直接將 JWT Access Token 與 Refresh Token 一併儲存在 LocalStorage 中,並透過 Axios 或 Fetch 的 Request Interceptor 於每個請求 Header 帶上 Authorization: Bearer <token>。

這種架構的主要工程瓶頸與資安風險如下:

  • XSS 盲區:LocalStorage 無法設定唯讀或隱藏屬性。只要網站注入任何第三方套件(如 NPM 供應鏈汙染)或存在反射型/儲存型 XSS 弱點,攻擊者即可透過 window.localStorage.getItem('token') 取得完整的 JWT,並將其傳送至外部惡意伺服器。
  • 無效的過期管理:LocalStorage 內容永不過期,除非透過 JavaScript 手動清除。若使用者未按下登出即關閉瀏覽器,憑證將長期留存在用戶端設備。
  • 自動發送機制缺失:LocalStorage 資料不會隨 HTTP Request 自動傳送,前端必須寫程式碼維護 Headers,增加開發複雜度與遺漏帶入 Token 的風險。

2. 三種儲存機制規格對照

Cookie、LocalStorage、SessionStorage 的容量、是否隨請求自動送出、生命週期與作用域對照表,整理在 〈前端資料儲存 Cookie、localStorage、sessionStorage 使用場景、限制、差異〉。


二、 關鍵機制解析:底層規範與注意事項

1. Cookie 屬性與安全性防禦鏈(HttpOnly, Secure, SameSite)

Cookie 透過 HTTP Response Header 的 Set-Cookie 指令設定,包含多個資安控制屬性:

  • HttpOnly:指示瀏覽器禁止任何用戶端指令碼(如 JavaScript 的 document.cookie)存取該 Cookie。這能阻斷攻擊者利用 XSS 直接竊取 Cookie 內文。
  • Secure:限制 Cookie 只在 HTTPS 請求中送出(localhost 例外),降低中間人攻擊(MITM)截獲明文憑證的風險。
  • SameSite:控制跨站請求時 Cookie 的發送行為,是防禦 CSRF 的縱深防禦層,但不能取代 Anti-CSRF Token:
  • 未設定 SameSite 時:Chromium 系瀏覽器(Chrome、Edge)會把它當成 Lax,而且設定未滿兩分鐘的 Cookie 仍會隨跨站頂層 POST 送出;Firefox 與 Safari 不套用這個預設。因此憑證 Cookie 一律明確寫出 SameSite。

2. Web Storage 容量限制與生命週期細節

Web Storage (LocalStorage/SessionStorage) 受同源政策(Same-Origin Policy, SOP)嚴格限制,必須 Protocol(協定)、Domain(網域)、Port(埠口) 三者完全一致才能共享資料。

  • LocalStorage 的跨頁共享:同源的所有分頁(Tabs)與視窗(Windows)共享同份 LocalStorage 資料,適合存放非敏感的偏好設定(如主題顏色、語言別)。
  • SessionStorage 的獨立隔離:SessionStorage 僅存在於建立它的該分頁內部。只有新頁面保有 window.opener(例如未指定 noopener 的 window.open(),或加上 rel="opener" 的連結)時,新分頁才會複製一份開啟者的 SessionStorage,之後兩者的資料更新完全獨立、互不影響。一般的 target="_blank" 連結在現行瀏覽器隱含 rel="noopener",新分頁不會複製,SessionStorage 是空白的;直接在網址列輸入相同 URL 開啟新分頁也一樣是空白。
Chrome 156 無頭模式、Windows 11 執行結果:window.open 與 rel="opener" 的新分頁讀到 parent-v1,target="_blank" 的新分頁讀到 null

3. JWT 存放策略:Memory vs Secure HttpOnly Cookie

JWT(JSON Web Token)是 RFC 7519 定義的緊湊、可放進 URL 的宣告(claims)傳遞格式,常用來當 Access Token;不論採用 JWT 或 Session ID,Token 的存放方式都決定了資安邊界。

策略 A:將 Access Token 與 Refresh Token 皆存於 LocalStorage

  • 優點:架構簡單,容易實作跨網域 API 呼叫。
  • 缺點:極易遭受 XSS 攻擊竊取,資安風險較高。

策略 B:將 Access Token 與 Refresh Token 皆存於 HttpOnly Cookie

  • 優點:完全防範 XSS 竊取 Token。
  • 缺點:容易面臨 CSRF 攻擊風險,伺服器必須配置 SameSite 屬性並實作 Anti-CSRF Token 機制。

策略 C(生產環境建議架構):Access Token 置於記憶體,Refresh Token 存於 Secure HttpOnly Cookie

  • Access Token(短時效,如 15 分鐘):僅存放在前端 JavaScript 記憶體變數中(如 React / Vue State 或 Context)。即使網站存在 XSS,攻擊者無法直接從 Storage 讀取值,只能利用記憶體空間;一旦頁面重新整理,Token 即從記憶體消失。
  • Refresh Token(長時效,如 7 天):存放在 HttpOnly; Secure; SameSite=Lax 的 Cookie 中,且該 Cookie 的 Path 限制為僅換發 Token 的 Endpoint(如 /api/auth/refresh),一般業務 API 不會收到 Refresh Cookie,降低發送頻率與外洩風險。
  • 運作機制:當頁面重新整理導致記憶體內的 Access Token 遺失時,前端自動向刷新 Endpoint 發起請求,瀏覽器自動附帶 Refresh Token Cookie,換取新的 Access Token 載入記憶體。

三、 實作範本:生產環境完整程式碼

範本一:後端 Express.js 安全 Cookie 設定與 Token 發行

以下示範如何在 Node.js Express 後端精確設定包含資安屬性的 Cookie,配合 Access Token 與 Refresh Token 機制:

import express from 'express';
import jwt from 'jsonwebtoken';
import cookieParser from 'cookie-parser';

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

const ACCESS_SECRET = 'your-access-secret-key';
const REFRESH_SECRET = 'your-refresh-secret-key';

// 登入路由
app.post('/api/auth/login', (req, res) => {
  const { username, password } = req.body;

  // 1. 驗證使用者身分(簡化範例)
  if (username !== 'admin' || password !== 'password123') {
    return res.status(401).json({ message: '帳號或密碼錯誤' });
  }

  const payload = { userId: 'usr_8892', role: 'admin' };

  // 2. 簽發短時效 Access Token (15 分鐘)
  const accessToken = jwt.sign(payload, ACCESS_SECRET, { expiresIn: '15m' });

  // 3. 簽發長時效 Refresh Token (7 天)
  const refreshToken = jwt.sign(payload, REFRESH_SECRET, { expiresIn: '7d' });

  // 4. 將 Refresh Token 寫入 Secure HttpOnly Cookie
  res.cookie('refreshToken', refreshToken, {
    httpOnly: true, // 阻斷 JavaScript 存取 (防 XSS)
    secure: process.env.NODE_ENV === 'production', // 僅允許 HTTPS
    sameSite: 'lax', // 防禦大部分跨站 CSRF 攻擊
    path: '/api/auth/refresh', // 限制僅向刷新路由發送 Cookie
    maxAge: 7 * 24 * 60 * 60 * 1000 // 7 天過期
  });

  // 5. 僅將 Access Token 回傳給前端記憶體保存
  return res.json({
    accessToken,
    expiresIn: 900
  });
});

// Refresh Token 換發路由
app.post('/api/auth/refresh', (req, res) => {
  const refreshToken = req.cookies.refreshToken;

  if (!refreshToken) {
    return res.status(401).json({ message: '缺乏 Refresh Token 憑證' });
  }

  try {
    const decoded = jwt.verify(refreshToken, REFRESH_SECRET);
    const newAccessToken = jwt.sign(
      { userId: decoded.userId, role: decoded.role },
      ACCESS_SECRET,
      { expiresIn: '15m' }
    );

    return res.json({ accessToken: newAccessToken, expiresIn: 900 });
  } catch (err) {
    return res.status(403).json({ message: 'Refresh Token 無效或已過期' });
  }
});

範本二:前端 Fetch Auth Client(記憶體 Token 管理與無感 Refresh 機制)

以下示範前端如何將 Access Token 存放在記憶體閉包(Closure)中,並在大部份請求失敗(401)時,自動呼叫後端發起 Refresh Cookie 換發 Token:

// AuthManager.ts
class AuthManager {
  private accessToken: string | null = null;
  private refreshPromise: Promise<string | null> | null = null;

  public setAccessToken(token: string | null): void {
    this.accessToken = token;
  }

  public getAccessToken(): string | null {
    return this.accessToken;
  }

  // 帶有自動重試機制的封裝 Fetch
  public async authenticatedFetch(url: string, options: RequestInit = {}): Promise<Response> {
    let token = this.getAccessToken();

    // 第一次嘗試發送請求
    const headers = new Headers(options.headers || {});
    if (token) {
      headers.set('Authorization', `Bearer ${token}`);
    }

    let response = await fetch(url, { ...options, headers });

    // 若回應 401 Unauthorized,嘗試透過 HttpOnly Cookie 換發 Token
    if (response.status === 401) {
      token = await this.refreshAccessToken();

      if (token) {
        // 換發成功,更新 Header 並重試原 API 請求
        const retryHeaders = new Headers(options.headers || {});
        retryHeaders.set('Authorization', `Bearer ${token}`);
        response = await fetch(url, { ...options, headers: retryHeaders });
      }
    }

    return response;
  }

  // 發起 Refresh Token 請求
  private async refreshAccessToken(): Promise<string | null> {
    // 避免多個併發請求同時觸發多次 Refresh
    if (this.refreshPromise) {
      return this.refreshPromise;
    }

    this.refreshPromise = (async () => {
      try {
        const res = await fetch('/api/auth/refresh', {
          method: 'POST',
          credentials: 'include' // 確保發送同源/跨源 Cookie
        });

        if (!res.ok) {
          throw new Error('Refresh failed');
        }

        const data = await res.json();
        this.setAccessToken(data.accessToken);
        return data.accessToken;
      } catch (err) {
        this.setAccessToken(null);
        // 清除 Token 並可跳轉至登入頁
        return null;
      } finally {
        this.refreshPromise = null;
      }
    })();

    return this.refreshPromise;
  }
}

export const authClient = new AuthManager();

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

Q1:SameSite 的 Strict、Lax、None 該怎麼選?

三種值在跨站請求時的送出差異與選擇方式,整理在 JWT 存放系列第 2 篇:跨網域 SameSite 與 CORS;本文範本的 Refresh Token Cookie 採用 SameSite=Lax。

Q2:當前端遭遇 XSS 弱點時,攻擊者如何繞過 JavaScript 存取限制或直接透過 DOM 竊取敏感憑證?

問題原因:開發者誤以為將 Token 放在記憶體或閉包中就能 100% 免疫 XSS。

解法:
如果憑證存於 LocalStorage/SessionStorage,XSS 攻擊者只需呼叫 Storage API 即可將資料傳出。若 Token 放在 JavaScript 記憶體中,雖然攻擊者無法直接用 Storage API 讀取,但攻擊者依然能藉由 XSS 挾持運作中的 Fetch / Axios 原生物件(Monkey Patching),截獲未來發出的所有 Request Headers,或是直接透過 DOM 操作發起偽造請求。因此,防範 XSS 的根本解決思路仍是輸出編碼(Output Encoding)與 HTML Sanitization,再以 CSP (Content Security Policy) 作為額外防禦層;儲存策略僅為降低洩漏機會的深層防衛手段。XSS 的類型與這些防禦的實作方式,可前往 〈XSS 跨站腳本攻擊三大類型與現代化防禦實作要點〉 觀看。

Q3:跨子網域共用 Cookie 時,Domain 屬性要怎麼設?

Domain 設成父網域的風險(含 Cookie Tossing),以及改用 host-only Cookie 與 __Host- 前綴的做法,整理在 JWT 存放系列第 2 篇。


五、 總結

選擇正確的前端儲存機制,關鍵在於評估資料的敏感度與存取模式:

  1. 一般偏好設定:選用 LocalStorage(持久化)或 SessionStorage(單一分頁 context)。
  2. 敏感身分憑證(JWT / Session ID):
    • Refresh Token 建議放進 HttpOnly + Secure + SameSite=Lax 的 Cookie。
    • Access Token 建議由前端 記憶體變數 進行管控,以兼顧防禦 XSS 與 CSRF 攻擊風險。

前端與 API 不同網域時 Cookie 怎麼帶,見 JWT 存放系列第 2 篇:跨網域 Cookie 設定;Refresh Token 的輪替與登出撤銷,見 第 3 篇:JWT Refresh Token Rotation 怎麼做?。


參考資料與延伸閱讀

發佈留言