JWT 開發者參考

JWT Claims 參考

除錯 JWT 時,我會用情境閱讀每個 claim:誰簽發、給誰、何時有效,以及應用程式真正理解哪些授權資料。

48 / 48

JWT 已註冊 Claims

iss

簽發者

stringRFC 7519 §4.1.1

識別簽發 JWT 的主體。

驗證: 與應用程式事先信任的 issuer 做完全一致比對。

sub

主體

stringRFC 7519 §4.1.2

在 issuer 命名空間內識別 JWT 代表的主體。

驗證: 先驗證 issuer,再只在該 issuer 命名空間內解讀。

aud

受眾

string | string[]RFC 7519 §4.1.3

識別 JWT 的預期接收者。

驗證: 要求包含 resource server 預期的 audience。

exp

到期時間

NumericDateRFC 7519 §4.1.4

此時間之後不應再接受 JWT。

驗證: 僅允許小幅且明確設定的 clock tolerance,exp 後拒絕。

nbf

生效時間

NumericDateRFC 7519 §4.1.5

此時間之前不應接受 JWT。

驗證: 除設定的 clock tolerance 外,nbf 前一律拒絕。

iat

簽發時間

NumericDateRFC 7519 §4.1.6

JWT 被簽發的時間。

驗證: 用於 token age/lifetime policy,並拒絕不合理的未來時間。

jti

JWT ID

stringRFC 7519 §4.1.7

JWT 的唯一識別碼。

驗證: 只有 replay 偵測或撤銷需要唯一性時才搭配伺服器狀態。

OpenID Connect 身分 / ID Token Claims

azp

授權對象

stringOIDC Core §2

識別 ID Token 被簽發給哪個授權對象。

驗證: 多 audience 或 client policy 要求時檢查。

nonce

Nonce

stringOIDC Core §2

把 ID Token 與瀏覽器/Client 的驗證請求綁定。

驗證: 與 authorization request 儲存的 nonce 完全一致比對。

auth_time

驗證時間

NumericDateOIDC Core §2

終端使用者完成驗證的時間。

驗證: max_age 或重新驗證政策依賴驗證時間時使用。

acr

驗證情境等級

stringOIDC Core §2

表示達成的驗證情境等級。

驗證: 只接受應用程式明確理解的 assurance level。

amr

驗證方法

string[]OIDC Core §2

表示實際使用的 password、MFA 等驗證方法。

驗證: 不要從未知值推測 assurance,依 issuer 定義解讀。

at_hash

Access Token 雜湊

stringOIDC Core §3.1.3.6

用雜湊衍生值把 Access Token 與 ID Token 綁定。

驗證: OIDC flow/response type 要求時驗證。

c_hash

授權碼雜湊

stringOIDC Core §3.3.2.11

用雜湊衍生值把授權碼與 ID Token 綁定。

驗證: OIDC response type 要求時驗證。

s_hash

State 雜湊

stringOIDC FAPI / registered claim

部分 OIDC/FAPI profile 用來把 state 與簽名回應綁定。

驗證: 只有目前 OIDC/FAPI profile 要求時才驗證。

sid

Session ID

stringOpenID Connect Session Management

識別 OpenID Provider 的 session。

驗證: 視為 issuer 範圍的 session metadata,不當作全域 user ID。

name

完整姓名

stringOIDC Core §5.1

終端使用者的完整顯示姓名。

驗證: 屬於個人資料顯示欄位,不當作穩定授權識別碼。

given_name

名字

stringOIDC Core §5.1

終端使用者的名字。

驗證: 作為顯示資料並考慮本地化。

family_name

姓氏

stringOIDC Core §5.1

終端使用者的姓氏。

驗證: 不要假設唯一性。

middle_name

中間名

stringOIDC Core §5.1

終端使用者的中間名。

驗證: 視為選填個人資料。

nickname

暱稱

stringOIDC Core §5.1

終端使用者的暱稱。

驗證: 只用於顯示。

preferred_username

偏好使用者名稱

stringOIDC Core §5.1

使用者偏好的簡短使用者名稱。

驗證: 不要假設全域唯一或永久不變。

profile

個人資料 URL

URL stringOIDC Core §5.1

終端使用者個人資料頁面的 URL。

驗證: 產生連結前先安全驗證 URL 處理。

picture

圖片 URL

URL stringOIDC Core §5.1

個人資料圖片 URL。

驗證: 顯示時視為不受信任的遠端內容。

website

網站 URL

URL stringOIDC Core §5.1

終端使用者網站 URL。

驗證: 視為不受信任的個人資料。

email

電子郵件

stringOIDC Core §5.1

終端使用者偏好的電子郵件地址。

驗證: 只有 email_verified=true 且 issuer 可信時才視為已驗證。

email_verified

電子郵件已驗證

booleanOIDC Core §5.1

表示 issuer 是否已確認該電子郵件的控制權。

驗證: 只有 issuer 與驗證方式都可信時才依賴。

gender

性別

stringOIDC Core §5.1

issuer 提供的性別資料。

驗證: 不需要時不要收集,優先資料最小化。

birthdate

出生日期

stringOIDC Core §5.1

終端使用者的出生日期。

驗證: 屬於敏感個人資料,不當作驗證因素。

zoneinfo

時區

stringOIDC Core §5.1

終端使用者的時區識別碼。

驗證: 只用於顯示或偏好設定。

locale

地區語系

BCP 47 stringOIDC Core §5.1

終端使用者的地區語系偏好。

驗證: 只用於顯示,不用於 trust decision。

phone_number

電話號碼

stringOIDC Core §5.1

終端使用者偏好的電話號碼。

驗證: 只有 phone_number_verified=true 且 issuer 可信時才視為已驗證。

phone_number_verified

電話已驗證

booleanOIDC Core §5.1

表示 issuer 是否已確認電話號碼的控制權。

驗證: 依 issuer 的驗證政策與方法解讀。

address

郵寄地址

objectOIDC Core §5.1

結構化的郵寄地址物件。

驗證: 顯示前檢查巢狀欄位,並視為敏感資料。

updated_at

個人資料更新時間

NumericDateOIDC Core §5.1

終端使用者資料最後更新的時間。

驗證: 只作為個人資料新鮮度 metadata。

OAuth Access Token / 授權 Claims

client_id

Client ID

stringRFC 9068 §2.2

識別與 Access Token 關聯的 OAuth client。

驗證: 只有 resource server policy 依賴特定 client 時才比對。

scope

OAuth Scopes

space-delimited stringRFC 9068 §2.2.3 / RFC 8693

表示 Access Token 具有的委派權限。

驗證: 只用 resource 理解且適用於 token audience 的 scope 進行授權。

roles

角色

string[]RFC 9068 §2.2.3.1 / RFC 7643

表示授權決策使用的角色值。

驗證: 明確定義 issuer/resource 語意,未知 role 預設拒絕。

groups

群組

string[]RFC 9068 §2.2.3.1 / RFC 7643

表示授權決策使用的群組成員資料。

驗證: 不要假設不同 issuer 的名稱或階層語意相同。

entitlements

權利

string[]RFC 9068 §2.2.3.1 / RFC 7643

表示權利或許可的 entitlement 值。

驗證: 將每個 entitlement 明確映射到允許操作。

cnf

確認資訊

objectRFC 7800

保存 Proof-of-Possession 金鑰確認資訊。

驗證: 實際驗證 token/profile 要求的 confirmation method。

act

實際行為者

objectRFC 8693 §4.1

在委派或 impersonation 情境中識別實際行為者。

驗證: 授權與稽核時區分 actor 與 subject。

may_act

可代理主體

objectRFC 8693 §4.4

識別被允許代表 subject 行動的主體。

驗證: 只在具明確 delegation policy 的 token exchange 使用。

Private / Vendor 授權 Claims

permissions

權限

string[]Private claim

常見的應用程式私有允許操作清單。

驗證: 明確定義此 private claim 的 issuer、audience 與 permission 語意。

role

角色

string | string[]Private claim

表示單一或多個角色的私有慣例。

驗證: 不要假設等同 roles,依 issuer 明確映射。

tenant

租戶

stringPrivate claim

用於租戶或組織 routing 的常見 private claim。

驗證: 不要只靠 tenant 建立 issuer trust,需與已驗證 context 比對。

org_id

組織 ID

stringPrivate claim

SaaS 授權模型中常見的組織識別碼。

驗證: 視為 issuer 特定值,resource membership 另外強制檢查。

token_use

Token 用途

stringVendor/private claim

Vendor 用來區分 access/identity 等 token 用途的慣例。

驗證: 只有 issuer 官方文件有定義時使用,能用標準 typ/profile 規則時優先使用標準。