本文提到的工具
邊閱讀邊在瀏覽器中開啟工具,立即試試整個流程。
什麼是 JWT?
只要您做過處理身分驗證的現代網頁應用程式,幾乎一定接觸過 JSON Web Token,通常簡稱為 JWT(讀作「jot」)。JWT 是一種精簡且對 URL 安全的方式,用來在雙方之間表示一組宣告(claim)。它由 RFC 7519 定義,已成為 REST API 中無狀態身分驗證的事實標準。

關鍵字是「無狀態」。傳統以工作階段為基礎的驗證,會由伺服器把工作階段資料存在記憶體或資料庫中;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):權杖所指的主體,通常是使用者 IDaud(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 驗證在實務上如何運作
典型流程如下:
- 登入:使用者把憑證(帳號與密碼)送到驗證端點。
- 簽發權杖:伺服器驗證憑證後,建立以密鑰或私鑰簽章的 JWT,回傳給用戶端。
- 後續請求:用戶端在
Authorization標頭中帶上 JWT:Authorization: Bearer <token>。 - 驗證:伺服器驗證簽章、檢查
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 天)。存取權杖過期時,用戶端把更新權杖送到專用端點,換取新的存取權杖。更新權杖每次使用後都應輪替(作廢並重新簽發)。
