什麼是 JWT?

只要您做過處理身分驗證的現代網頁應用程式,幾乎一定接觸過 JSON Web Token,通常簡稱為 JWT(讀作「jot」)。JWT 是一種精簡且對 URL 安全的方式,用來在雙方之間表示一組宣告(claim)。它由 RFC 7519 定義,已成為 REST API 中無狀態身分驗證的事實標準。

理解 JWT(JSON Web Token):結構、宣告與安全除錯

關鍵字是「無狀態」。傳統以工作階段為基礎的驗證,會由伺服器把工作階段資料存在記憶體或資料庫中;JWT 則把所有必要資訊都放在權杖本身。伺服器不需要查任何東西,只要驗證簽章並信任內容即可。

原始的 JWT 長這樣:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyXzEyMyIsInJvbGUiOiJhZG1pbiIsImV4cCI6MTczNjkwMDgwMH0.Xe4kJl7YQoLPkZ3r9Vv2mHgGqNtWbF8sDcA1eRfuByk

三段以 Base64Url 編碼、以點號分隔的片段,每一段各有特定用途。


三段式結構

1. 標頭(Header)

標頭是描述權杖本身的 JSON 物件,主要說明使用哪種演算法簽章。

{
  "alg": "HS256",
  "typ": "JWT"
}

alg 指定簽章演算法。常見的值包括:

演算法 類型 備註
HS256 對稱(HMAC-SHA256) 簽章與驗證共用同一把密鑰
RS256 非對稱(RSA-SHA256) 私鑰簽章,公鑰驗證
ES256 非對稱(ECDSA-SHA256) 金鑰比 RSA 小,越來越普及
none 無簽章 危險:正式環境絕對不要接受

2. 酬載(Payload)

酬載存放實際資料,每一筆資料稱為一個宣告(claim)。

{
  "sub": "user_123",
  "name": "Alex Chen",
  "role": "admin",
  "iat": 1736814400,
  "exp": 1736900800
}

宣告分為三類:

已註冊宣告(由 RFC 7519 標準化):

  • iss(Issuer):簽發權杖的一方,例如 "https://auth.example.com"
  • sub(Subject):權杖所指的主體,通常是使用者 ID
  • aud(Audience):權杖預定給誰使用
  • exp(Expiration Time):超過此 Unix 時間戳記後,權杖必須被拒絕
  • iat(Issued At):權杖建立時的 Unix 時間戳記
  • nbf(Not Before):在此 Unix 時間戳記之前,不得接受權杖

公開宣告:定義於 IANA 的 JWT 宣告註冊表,或使用 URI 命名空間以避免衝突。

私有宣告:雙方約定的自訂宣告,例如上例中的 role 或 plan。

重要提醒: 酬載只是被編碼,並沒有被加密。任何拿到權杖的人,只要做 Base64 解碼就能讀到酬載。請勿把密碼、信用卡號或其他敏感資料放進 JWT 酬載。

3. 簽章(Signature)

簽章的計算方式如下(以 HS256 為例):

HMAC-SHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secretKey
)

簽章讓 JWT 具備「遭竄改即可察覺」的特性。只要有人改動標頭或酬載中的任何一個字元,簽章就不再相符,權杖會被拒絕。伺服器不需要把權杖存在任何地方,只要重新計算預期的簽章,與收到的簽章比對即可。


JWT 驗證在實務上如何運作

典型流程如下:

  1. 登入:使用者把憑證(帳號與密碼)送到驗證端點。
  2. 簽發權杖:伺服器驗證憑證後,建立以密鑰或私鑰簽章的 JWT,回傳給用戶端。
  3. 後續請求:用戶端在 Authorization 標頭中帶上 JWT:Authorization: Bearer <token>。
  4. 驗證:伺服器驗證簽章、檢查 exp 並讀取宣告,整個過程都不需要查詢資料庫。
// 伺服器端驗證範例(Node.js,使用 jose 函式庫)
import * as jose from 'jose';

async function verifyRequest(authHeader) {
  const token = authHeader?.split(' ')[1];
  if (!token) throw new Error('No token provided');

  const secret = new TextEncoder().encode(process.env.JWT_SECRET);
  const { payload } = await jose.jwtVerify(token, secret, {
    issuer: 'https://auth.example.com',
    audience: 'https://api.example.com',
  });

  return payload; // { sub, role, exp, ... }
}

JWT 與工作階段權杖的比較

兩種做法都可行,要選哪一種取決於您的架構。

面向 JWT(無狀態) 工作階段權杖(有狀態)
伺服器儲存 不需要 工作階段儲存區(Redis、資料庫)
撤銷 困難:必須等到過期,或維護封鎖清單 容易:從儲存區刪除即可
水平擴充 自然:任何伺服器都能驗證 需要共用的工作階段儲存區
權杖大小 較大(帶有宣告) 小(只有 ID)
適用情境 微服務、API、行動應用程式 傳統網頁應用程式

常見的安全陷阱

alg: none 攻擊

早期某些 JWT 函式庫允許 alg: none,也就是不需要簽章。攻擊者可以移除簽章並捏造任意酬載。請務必明確指定伺服器接受哪些演算法,並拒絕 none。

// jose:預設就是安全的,必須提供金鑰,且會拒絕未簽章的權杖
await jose.jwtVerify(token, secret); // 若 alg 為 "none" 就會拋出錯誤

演算法混淆(RS256 → HS256)

若伺服器預期 RS256(非對稱),但攻擊者把標頭改成 HS256(對稱),有些函式庫會把公鑰當成 HMAC 密鑰。公鑰本來就是公開的,攻擊者因此能偽造有效的權杖。解法:在伺服器端鎖定接受的演算法。

把 JWT 存在 localStorage

存在 localStorage 的權杖,頁面上的任何 JavaScript 都能存取,容易受到 XSS 攻擊。建議改用 JavaScript 無法存取的 HttpOnly Cookie。

沒有更新機制的長效權杖

把 exp 設成一週或一個月很誘人,但這代表被竊取的權杖會長時間有效。請使用短效的存取權杖(15~60 分鐘),搭配妥善保管的長效更新權杖。


如何手動解碼 JWT

酬載只是經過 Base64Url 編碼,所以不需要任何函式庫就能解碼:

function decodeJWT(token) {
  const parts = token.split('.');
  if (parts.length !== 3) return null;

  // Base64Url → Base64 → 解碼
  const decode = (str) =>
    JSON.parse(atob(str.replace(/-/g, '+').replace(/_/g, '/')));

  return {
    header:  decode(parts[0]),
    payload: decode(parts[1]),
    // 注意:沒有密鑰或公鑰,就無法驗證簽章(parts[2])
  };
}

const { header, payload } = decodeJWT('eyJhbGci...');
console.log(payload.exp); // 1736900800

用於除錯完全沒問題。但請記住:解碼不等於驗證。在信任任何宣告之前,務必先在伺服器驗證簽章。


在瀏覽器中安全地除錯

除錯正式環境的權杖時,您會面臨兩難:需要看裡面有什麼,但把真實使用者的 JWT 貼到第三方線上工具又有安全風險。這些權杖可能含有使用者 ID、角色與其他敏感的中繼資料。

DevToolKits 的 JWT 工具 完全在您的瀏覽器內處理權杖,不會傳送任何資料到伺服器。您可以自己驗證:開啟瀏覽器的網路分頁,貼上權杖後會看到沒有任何對外請求。您也可以提供密鑰或公鑰,在用戶端驗證簽章。


宣告(claim)檢查(警告)

JWT 除錯工具除了驗證簽章之外,還會檢查解碼後 payload 中的宣告並顯示警告。即使簽章正確,像下面這樣的權杖在實際運作中也會出問題。

警告 觸發條件
沒有 exp 永不過期的權杖
有效期間偏長 exp − iat 超過 24 小時(例如 1d 1h)
iat 在未來 比目前時間早超過 60 秒(容許時鐘誤差)
nbf 晚於 exp 在生效之前就已過期
時間為毫秒 exp、iat、nbf 超過 10^11(JWT 的時間以秒為單位)
iss 與預期值不同 輸入「預期的簽發者」時
aud 不含預期值 輸入「預期的受眾」時(aud 可為字串或陣列,任一相符即通過)

iss 與 aud 只有在輸入預期值時才會檢查。可用來確認 API 端的驗證是否一定會檢查 iss、aud,或找出各環境的設定錯誤(例如把正式環境的 aud 用在預備環境)。

2026 年 11 月新增的功能

  • 可產生測試用金鑰對(ES256、RS256、PS256、ES384、EdDSA)。私鑰以 PKCS#8 PEM 與 JWK 提供,公鑰以 SPKI PEM 與 JWK 提供,按「用於上方簽署」即可填入簽署表單。
  • 也可用私鑰 JWK 簽署。金鑰在瀏覽器內產生,不會傳送。僅限測試,請勿用於正式環境。

在工具中試用

常見問題

JWT 的大小上限是多少?

JWT 規格沒有硬性的大小限制,但實務上有限制。HTTP 標頭有大小上限(通常每個標頭 8 KB),瀏覽器也限制 Cookie 的大小(約 4 KB)。請讓酬載保持精簡,只放接收端真正需要讀取的宣告。

可以在到期前讓 JWT 失效嗎?

原生做不到,這是無狀態權杖的取捨之一。常見的替代做法有:(1) 在伺服器端維護已撤銷權杖 ID(存放於 jti 宣告)的封鎖清單、(2) 使用非常短的到期時間,或 (3) 輪替簽章金鑰,並讓舊金鑰只在短暫的期間內被接受。

JWT 加密(JWE)與 JWT 簽章(JWS)不一樣嗎?

不一樣。一般的 JWT 是 JWS(JSON Web Signature):酬載可以讀取,但遭竄改能被察覺。JWE(JSON Web Encryption)會加密酬載,沒有解密金鑰就讀不到內容。JWS 遠比 JWE 常見,只有當酬載本身含有不該在傳輸過程中被看見的資料時,才使用 JWE。

所有服務可以共用同一把 JWT 密鑰嗎?

不可以。請依服務或權杖類型(存取權杖與更新權杖)使用不同的簽章金鑰。這樣一把金鑰外洩時,影響範圍較小,也更容易輪替金鑰。

權杖更新該怎麼處理?

簽發短效的存取權杖(例如 15 分鐘),以及存放在 HttpOnly Cookie 中的長效更新權杖(例如 7 天)。存取權杖過期時,用戶端把更新權杖送到專用端點,換取新的存取權杖。更新權杖每次使用後都應輪替(作廢並重新簽發)。