Token Introspection

Token Introspection 由 RFC 7662 定義，讓 Resource Server 能夠向 Authorization Server 即時查詢一個 Token 是否有效，以及該 Token 的相關資訊（持有者、有效期限、授權範圍等）。

解決什麼問題

Resource Server 收到 Client 的 API 請求時，需要驗證附帶的 Access Token 是否有效。有兩種常見做法：

方式	說明	適用場景
本地驗證（JWT）	Resource Server 自行解析並驗證 JWT 簽章	Token 是 JWT 格式，效能優先
Introspection（遠端查詢）	向 Authorization Server 確認 Token 狀態	Opaque Token，或需要即時確認是否已撤銷

Token Introspection 特別適合以下情況：

Token 是不透明字串（Opaque Token），Resource Server 無法自行解析
需要確認 Token 是否已被撤銷（JWT 本地驗證無法即時得知撤銷狀態）
多個 Resource Server 共用同一個 Authorization Server

請求格式

Resource Server 對 Authorization Server 的 Introspection 端點發送 POST 請求：

POST /introspect HTTP/1.1
Host: auth.example.com
Authorization: Basic BASE64(rs_client_id:rs_client_secret)
Content-Type: application/x-www-form-urlencoded

token=ACCESS_TOKEN_VALUE

⚠️ 注意：Introspection 端點本身需要認證（通常是 Resource Server 的 Client 憑證），防止任意人查詢 Token 資訊。

可選參數：

參數	說明
`token`	要查詢的 Token（必填）
`token_type_hint`	提示 Token 類型（`access_token` 或 `refresh_token`），可加速查詢

回應格式

Token 有效

{
  "active": true,
  "client_id": "my-app",
  "username": "alice",
  "scope": "read:profile read:email",
  "sub": "user-123",
  "aud": "https://api.example.com",
  "iss": "https://auth.example.com",
  "exp": 1742040000,
  "iat": 1742036400,
  "token_type": "Bearer"
}

Token 無效或已撤銷

{
  "active": false
}

active: false 涵蓋所有無效狀態：Token 不存在、已過期、已撤銷，或不屬於這個 Resource Server。

重要欄位說明

欄位	說明
`active`	必填，`true` 代表有效，`false` 代表無效
`scope`	授權範圍，空格分隔的字串
`client_id`	發起授權的 Client
`sub`	Token 代表的使用者識別碼
`exp`	到期時間（Unix timestamp）
`iat`	核發時間（Unix timestamp）
`aud`	允許使用此 Token 的受眾（Audience）

效能考量

Introspection 是一次網路請求，如果每個 API call 都做 Introspection 會產生顯著延遲。常見的最佳化方式：

短期快取：Resource Server 本地快取 Introspection 結果，時間不超過 Token 的剩餘有效期
搭配 JWT：Token 核發時使用 JWT，本地驗證簽章與有效期；只在需要確認撤銷狀態時才做 Introspection
Token 撤銷通知：搭配 Token Revocation (RFC 7009) 讓 Resource Server 主動更新快取

與 JWT 本地驗證的比較

面向	Token Introspection	JWT 本地驗證
Token 格式	Opaque Token 或 JWT	必須是 JWT
即時撤銷	✅ 每次查詢 Authorization Server	❌ 需等 Token 自然過期
效能	❌ 每次驗證需網路請求	✅ 本地計算
架構耦合	Resource Server 依賴 Authorization Server 可用性	無依賴
適用規模	中小型、需要即時撤銷的系統	大型分散式系統