JWT 是什麼? JWT 是 JSON Web Token 的縮寫,是 RFC 7519 定義的一種 Token 格式:把一組「宣告」(claims,例如這個 Token 屬於誰、什麼時候到期)寫成 JSON,再加上簽章,壓縮成一串可以放進 HTTP 標頭或網址的字串。RFC 7519 提到建議的唸法和英文單字 "jot" 相同。第一次看到 JWT,通常是在登入 API 的回應裡,看到一長串 eyJ 開頭、中間有兩個句點的字串。本文用一個實際的 JWT 拆開三段結構,說明簽章與驗證流程,以及新手最容易誤會的一點:JWT 的內容可以被任何人讀取。
JWT 是什麼:三段以句點相連的字串
RFC 7519 的說明是:JWT 是一種緊湊(compact)的宣告表示格式,設計給 HTTP Authorization 標頭、URI 查詢參數這類空間有限的環境使用。JWT 永遠以 JWS Compact Serialization(簽章)或 JWE Compact Serialization(加密)表示,也就是一串用句點(.)分隔的 URL-safe 片段,每一段都是 base64url 編碼的值。
簽章版本的 JWT(本文只講這一種,也是最常見的)有三段:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyLTEyMyIsIm5hbWUiOiJBbGljZSIsImlhdCI6MTcwMDAwMDAwMCwiZXhwIjoxNzAwMDAzNjAwfQ.Cj42-ST_X6in2Ysp6sy5k85fsZ0Wq2RZp-u5k1tVB4k
| 位置 | 名稱 | 內容 |
|---|---|---|
| 第 1 段 | Header | 描述這個 Token 的演算法等資訊,JSON 經 base64url 編碼 |
| 第 2 段 | Payload | 宣告(claims),也就是 Token 要傳遞的資料,JSON 經 base64url 編碼 |
| 第 3 段 | Signature | 對前兩段計算出的簽章,再經 base64url 編碼 |
jwt.io 的介紹頁也是這樣描述:JWT 的緊湊形式由三個以句點分隔的部分組成,分別是 Header、Payload 與 Signature。
JWT 三段結構:Header、Payload、Signature
Header:說明用什麼演算法簽章
上面那串 JWT 的第 1 段解碼後是:
{"alg":"HS256","typ":"JWT"}
alg:簽章使用的演算法。HS256代表 HMAC 搭配 SHA-256(RFC 7518 的定義)。依 RFC 7515,alg一定要存在。typ:Token 的類型,常見值是JWT。RFC 7519 §5.1 說明,應用程式已經知道物件就是 JWT 時,通常不會用到這個欄位。
Payload:放宣告(claims)
第 2 段解碼後是:
{"sub":"user-123","name":"Alice","iat":1700000000,"exp":1700003600}
RFC 7519 把宣告分成三類:註冊宣告(Registered)、公開宣告(Public)與私有宣告(Private)。註冊宣告是 RFC 預先定義好名稱的幾個欄位,名稱都很短,因為 JWT 的設計目標之一就是精簡。常見的有:
| 宣告 | 全名 | 意思 |
|---|---|---|
iss | Issuer | 誰簽發這個 JWT |
sub | Subject | 這個 JWT 描述的對象,例如使用者 ID |
aud | Audience | 這個 JWT 預期給誰使用;處理者不在 aud 內時,JWT 必須被拒絕 |
exp | Expiration Time | 到期時間;當下時間必須早於這個時間,JWT 才能被接受 |
nbf | Not Before | 在這個時間之前不得接受 |
iat | Issued At | 簽發時間 |
jti | JWT ID | JWT 的唯一識別碼,可用來防止重送 |
這些註冊宣告全部都是選用的(OPTIONAL),RFC 7519 的原話是「沒有一個宣告被設計成所有情況下都強制使用」,哪些宣告必填由使用 JWT 的應用程式自己決定。exp、nbf、iat 的值是 NumericDate,也就是自 1970-01-01T00:00:00Z UTC 起算的秒數,不是毫秒。範例裡的 exp 比 iat 多 3600,代表簽發後一小時到期。
除了註冊宣告,也能放自訂欄位(例如上面的 name),但 RFC 7519 提醒:私有宣告名稱可能和別人衝突,使用時要小心。
Signature:防止內容被竄改
簽章是對「第 1 段 + . + 第 2 段」這串文字計算出來的。RFC 7515 把這串輸入稱為 JWS Signing Input。以 HS256 為例,做法是用密鑰對這串文字做 HMAC-SHA256,再把結果 base64url 編碼,放在第 3 段。
整個組合方式就是 RFC 7515 的公式:
BASE64URL(Header) + "." + BASE64URL(Payload) + "." + BASE64URL(Signature)
簽章的作用是讓拿到 JWT 的人可以確認「這串內容是持有密鑰的人簽的,而且中途沒被改過」。只要 Header 或 Payload 任何一個字元被改動,重新計算出的簽章就會和第 3 段對不上。
Base64url 不是加密:Payload 任何人都能讀
新手最常見的誤會是把 JWT 當成「加密過的字串」。實際上 Header 與 Payload 只是經過 base64url 編碼,編碼不需要密鑰,任何人拿到 JWT 都能還原。
base64url 是 RFC 4648 第 5 節定義的編碼,和一般 Base64 幾乎相同,只有第 62、63 個字元不同:+ 換成 -、/ 換成 _,讓結果能安全放進網址與檔名。JWT 使用的 base64url 還會省略結尾的 = 填充字元(RFC 7515 的定義)。RFC 4648 也特別說明,這種編碼不應該只稱為 base64。
jwt.io 的介紹寫得很直接:簽署過的 Token 雖然能防止被竄改,但內容任何人都讀得到,除非 Token 另外加密,否則不要把機密資訊放進 Payload 或 Header。RFC 7519 §12 也說,最簡單的做法就是不要把隱私敏感資訊放進 JWT。
整理成一句話:簽章保證「沒被改過、是誰簽的」,不保證「別人看不到」。 如果真的需要隱藏內容,RFC 7519 提到的做法是使用加密的 JWT(JWE),但那是另一套格式,本文不展開。
JWT 簽章與驗證流程
用 HS256 時,簽發與驗證流程如下:
- 簽發:伺服器組出 Header 與 Payload,各自 base64url 編碼後用句點相連,再用密鑰計算 HMAC-SHA256,把簽章 base64url 編碼後接在最後。
- 傳送:客戶端拿到 JWT,之後的請求把它帶回伺服器。jwt.io 說明,JWT 最常見的情境是授權:使用者登入後,每個後續請求都帶著 JWT,通常放在
Authorization標頭,使用Bearer結構。 - 驗證:伺服器收到 JWT 後,把前兩段重新做一次 HMAC,和第 3 段比對。比對一致才代表內容沒被改過。
- 檢查宣告:簽章通過後,再檢查
exp有沒有過期、aud、iss是否符合自己的預期。
這個流程的重點是:驗證簽章之前,不能相信 Payload 裡的任何內容。 RFC 7519 §11.1 說明,JWT 的內容必須經過密碼學保護,並綁定信任決策所需的情境,才能用來做信任決策。
HS256 屬於對稱式演算法,簽發與驗證用同一把密鑰。RFC 7518 還列了非對稱的演算法,例如 RS256(RSA)與 ES256(ECDSA),用私鑰簽發、公鑰驗證,適合簽發者與驗證者是不同系統的情況。依 RFC 7518 的表格,HS256 是必須實作(Required)的演算法,RS256 為建議(Recommended),ES256 為 Recommended+。
用 Node.js 內建模組產生與驗證 JWT
以下範例只使用 Node.js 內建的 crypto 與 Buffer,不需要安裝任何套件。Buffer 的 'base64url' 編碼就是 RFC 4648 §5 的格式。範例的密鑰 demo-secret-... 是示範用字串,正式環境要改用隨機產生、長度夠的密鑰並放在環境變數:RFC 7518 要求 HS256 的密鑰長度至少和雜湊輸出相同(256 位元),RFC 8725 §3.5 也規定人類好記的密碼不得直接當作 HS256 的密鑰。
const crypto = require('node:crypto');
// 示範用密鑰,正式環境請改用隨機產生、至少 32 位元組的密鑰並放在環境變數
const SECRET = 'demo-secret-change-me-32-bytes-min!!';
const b64u = (input) => Buffer.from(input).toString('base64url');
function sign(payload) {
const header = { alg: 'HS256', typ: 'JWT' };
const signingInput = `${b64u(JSON.stringify(header))}.${b64u(JSON.stringify(payload))}`;
const signature = crypto.createHmac('sha256', SECRET).update(signingInput).digest('base64url');
return `${signingInput}.${signature}`;
}
function verify(token, nowSec = Math.floor(Date.now() / 1000)) {
const parts = token.split('.');
if (parts.length !== 3) throw new Error('格式錯誤:必須是三段');
const [h, p, s] = parts;
const header = JSON.parse(Buffer.from(h, 'base64url').toString('utf8'));
// 演算法由伺服器決定,不信任 Token 自己宣告的 alg
if (header.alg !== 'HS256') throw new Error(`不接受的演算法:${header.alg}`);
const expected = crypto.createHmac('sha256', SECRET).update(`${h}.${p}`).digest();
const actual = Buffer.from(s, 'base64url');
if (expected.length !== actual.length || !crypto.timingSafeEqual(expected, actual)) {
throw new Error('簽章不符');
}
const payload = JSON.parse(Buffer.from(p, 'base64url').toString('utf8'));
if (typeof payload.exp !== 'number' || nowSec >= payload.exp) throw new Error('Token 已過期或缺少 exp');
return payload;
}
const payload = { sub: 'user-123', name: 'Alice', iat: 1700000000, exp: 1700003600 };
const token = sign(payload);
console.log('1. 產生的 JWT:');
console.log(token);
console.log('\n2. 不需要密鑰就能解碼 Payload:');
console.log(JSON.parse(Buffer.from(token.split('.')[1], 'base64url').toString('utf8')));
console.log('\n3. 驗證(時間 1700000100,尚未過期):');
console.log(verify(token, 1700000100));
console.log('\n4. 驗證(時間 1700003600,已到 exp):');
try { verify(token, 1700003600); } catch (e) { console.log('失敗:', e.message); }
console.log('\n5. 竄改 Payload 後驗證:');
const [h, , s] = token.split('.');
const forged = `${h}.${b64u(JSON.stringify({ ...payload, name: 'Admin' }))}.${s}`;
try { verify(forged, 1700000100); } catch (e) { console.log('失敗:', e.message); }
console.log('\n6. alg 改成 none 且沒有簽章:');
const none = `${b64u(JSON.stringify({ alg: 'none', typ: 'JWT' }))}.${b64u(JSON.stringify(payload))}.`;
try { verify(none, 1700000100); } catch (e) { console.log('失敗:', e.message); }
為了讓輸出固定,範例把簽發時間與「現在時間」都寫成固定秒數;正式使用時 nowSec 就用預設的目前時間。Node.js v22.20.0、Windows 11 的執行輸出如下:
1. 產生的 JWT:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyLTEyMyIsIm5hbWUiOiJBbGljZSIsImlhdCI6MTcwMDAwMDAwMCwiZXhwIjoxNzAwMDAzNjAwfQ.Cj42-ST_X6in2Ysp6sy5k85fsZ0Wq2RZp-u5k1tVB4k
2. 不需要密鑰就能解碼 Payload:
{ sub: 'user-123', name: 'Alice', iat: 1700000000, exp: 1700003600 }
3. 驗證(時間 1700000100,尚未過期):
{ sub: 'user-123', name: 'Alice', iat: 1700000000, exp: 1700003600 }
4. 驗證(時間 1700003600,已到 exp):
失敗: Token 已過期或缺少 exp
5. 竄改 Payload 後驗證:
失敗: 簽章不符
6. alg 改成 none 且沒有簽章:
失敗: 不接受的演算法:none

從輸出可以看到幾件事:
- 第 2 項沒有用到密鑰,就把 Payload 還原了,這就是前面說的「編碼不是加密」。
- 第 4 項的
exp檢查採「現在時間必須早於exp」,所以剛好等於exp的那一秒也算過期,和 RFC 7519 §4.1.4 的規則一致。 - 第 5 項改了 Payload 卻沒有密鑰重簽,簽章對不上,驗證失敗。
- 第 6 項是下一節要講的
alg: none問題。
程式裡比對簽章用的是 crypto.timingSafeEqual:RFC 7518 要求 HMAC 的比對必須以 constant-time 方式進行,避免計時攻擊;Node.js 文件說明這個函式使用 constant-time 演算法,適合比較 HMAC digest,且兩個參數的位元組長度必須相同,所以程式先比長度。範例的簽章演算也可以和 RFC 7515 附錄 A.1 的 HS256 範例對照:用該附錄的金鑰對同一串輸入計算,得到的簽章和 RFC 文件列出的值相同。
驗證 JWT 的注意事項
不要信任 Token 自己宣告的演算法
alg 寫在 Token 的 Header 裡,攻擊者可以任意修改。RFC 8725 §2.1 列出兩種已知的攻擊:把演算法改成 none,有些函式庫會直接信任而不檢查簽章;或把 RS256 改成 HS256,讓函式庫拿 RSA 公鑰當 HMAC 密鑰驗證。
對應做法是 RFC 8725 §3.1:函式庫必須讓呼叫端指定支援的演算法集合,不得使用其他演算法。RFC 7518 §3.6 也規定,實作預設不得接受 alg 為 none 的 Unsecured JWS。所以上面範例的 verify 只認 HS256。
簽章通過後還要檢查宣告
簽章正確只代表「內容沒被改過、是持有密鑰的人簽的」,不代表這個 Token 現在該被接受。至少要檢查:
exp:Token 是否已過期。RFC 7519 允許實作保留一點時鐘誤差的寬限,但也說明通常不超過幾分鐘。aud:Token 是不是發給自己的。RFC 7519 規定,aud存在而自己不在其中時必須拒絕。iss:RFC 8725 §3.8 規定,JWT 含有iss時,應用程式必須驗證簽章用的金鑰確實屬於該簽發者。
其他要點
- 密鑰要夠強、要保密:
HS256的密鑰長度至少 256 位元,且不能直接拿人類好記的密碼;簽發與驗證都用同一把密鑰,洩漏就等於任何人都能偽造 Token。 - 全程使用 HTTPS:RFC 7519 §12 提到,含有未加密隱私資訊的 JWT,應只透過支援端點驗證與加密的協定(例如 TLS)傳輸。
- Payload 只放必要且不敏感的資料:理由同上一節。
- 過期時間不要省:
exp是選用的,但沒有exp的 Token 一旦外流就沒有時間限制。
JWT 放在瀏覽器哪裡比較安全、Token 過期後怎麼換新,是另外的主題。放在 localStorage、Cookie 還是記憶體的比較,詳細可前往〈JWT 存放位置怎麼選?LocalStorage、Cookie 與記憶體的資安比較〉;Refresh Token 輪替與登出撤銷,詳細可前往〈JWT Refresh Token Rotation 怎麼做?雙權杖輪替、重複使用偵測與登出撤銷〉。如果想先了解 Cookie 與 Web Storage 的差異,可前往〈前端資料儲存 Cookie、localStorage、sessionStorage 使用場景、限制、差異〉。
JWT 常見用途
依 jwt.io 的介紹,JWT 有兩個典型用途:
- 授權(Authorization):使用者登入後,後續每個請求都帶著 JWT,伺服器依 JWT 判斷可以存取哪些路由、服務與資源。jwt.io 指出這是 JWT 最常見的情境,單一登入(Single Sign-On)也廣泛使用 JWT。
- 資訊交換(Information Exchange):在兩方之間傳遞資訊,因為有簽章,接收方可以確認內容是誰簽的、有沒有被改過。
如果 JWT 是放在網頁的 Cookie 裡傳送,還會牽涉到 CSRF 風險,可參考〈CSRF 跨站請求偽造攻擊原理與 Anti-CSRF Token 防禦實作〉與〈跨網域 Cookie 設定:SameSite、CORS credentials 與 CSRF 防禦〉。
常見問題
JWT 內容加密了嗎?
沒有。一般看到的簽章版 JWT,Header 與 Payload 只是 base64url 編碼,任何人都能解碼閱讀,簽章只負責防竄改。RFC 7519 另外定義了用 JWE 表示的加密 JWT,但那是不同的格式與流程。
解碼 JWT 就等於驗證嗎?
不等於。jwt.io 的說明是:解碼只是把各段 base64url 還原並解析 JSON,不會驗證簽章;驗證則是確認密碼學簽章,確保 Token 由可信任的一方簽發且沒被竄改。兩者都需要,驗證通過前不應該信任 Payload。
JWT 的 exp 用秒還是毫秒?
秒。RFC 7519 的 NumericDate 是自 1970-01-01T00:00:00Z UTC 起算的秒數。JavaScript 的 Date.now() 回傳毫秒,要除以 1000 再取整數(範例的 Math.floor(Date.now() / 1000))。
總結
JWT 是 RFC 7519 定義的 Token 格式,由 Header、Payload、Signature 三段以句點相連,每段都是 base64url 編碼。簽章用來確認內容沒被改過、是持有密鑰的人簽的;但 Header 與 Payload 只是編碼,任何人都能讀,所以不要放機密資訊。驗證時要由伺服器決定允許的演算法,簽章通過後再檢查 exp、aud、iss 等宣告。
參考資料與延伸閱讀
- RFC 7519:JSON Web Token (JWT)
- RFC 7515:JSON Web Signature (JWS)
- RFC 7518:JSON Web Algorithms (JWA)
- RFC 8725:JSON Web Token Best Current Practices
- RFC 4648:The Base16, Base32, and Base64 Data Encodings
- Introduction to JSON Web Tokens:jwt.io
- Buffer:Node.js v22 文件
- Crypto:Node.js v22 文件
- JSON Web Token Cheat Sheet:OWASP
- 前端資料儲存 Cookie、localStorage、sessionStorage 使用場景、限制、差異
- CSRF 跨站請求偽造攻擊原理與 Anti-CSRF Token 防禦實作
發佈留言