自訂 ID 權杖 (ID token)
簡介
ID 權杖 (ID token) 是由 OpenID Connect (OIDC) 協議定義的一種特殊權杖。它作為授權伺服器（Logto）在使用者成功驗證後簽發的身分聲明，攜帶已驗證使用者身分的宣告 (Claims)。
與用於存取受保護資源的 存取權杖 (Access tokens) 不同，ID 權杖專為向用戶端應用程式傳遞已驗證使用者身分而設計。它們是 JSON Web Token (JWT)，包含有關驗證事件與已驗證使用者的宣告 (Claims)。
ID 權杖宣告 (Claims) 的運作方式
在 Logto 中，ID 權杖宣告 (Claims) 分為兩類：
- 標準 OIDC 宣告 (Standard OIDC claims)：由 OIDC 規範定義，完全由驗證時請求的權限範圍 (Scopes) 決定。
- 擴充宣告 (Extended claims)：Logto 擴充以攜帶額外身分資訊的宣告，受 雙重條件模型（Scope + Toggle） 控制。
標準 OIDC 宣告 (Standard OIDC claims)
標準宣告完全遵循 OIDC 規範。它們是否被納入 ID 權杖，僅取決於你的應用程式在驗證時請求的權限範圍 (Scopes)。Logto 不提供停用或選擇性排除個別標準宣告的選項。
下表顯示標準權限範圍與其對應宣告的對應關係：
| 權限範圍 (Scope) | 宣告 (Claims) |
|---|---|
openid | sub |
profile | name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, updated_at |
email | email, email_verified |
phone | phone_number, phone_number_verified |
address | address |
例如，若你的應用程式請求 openid profile email 權限範圍，ID 權杖將包含來自 openid、profile 和 email 權限範圍的所有宣告。
擴充宣告 (Extended claims)
除了標準 OIDC 宣告外，Logto 還擴充了額外宣告，攜帶 Logto 生態系專屬的身分資訊。這些擴充宣告遵循 雙重條件模型 才會被納入 ID 權杖：
- 權限範圍條件 (Scope condition)：應用程式必須在驗證時請求對應的權限範圍。
- 控制台開關 (Console toggle)：管理員必須在 Logto Console 中啟用該宣告納入 ID 權杖。
兩個條件必須同時滿足。權限範圍 (Scope) 屬於協議層級的存取聲明，開關 (Toggle) 則屬於產品層級的資訊暴露控制——兩者職責明確且不可互相取代。
可用的擴充權限範圍與宣告
| 權限範圍 (Scope) | 宣告 (Claims) | 說明 (Description) | 預設納入 (Included by default) |
|---|---|---|---|
custom_data | custom_data | 儲存在使用者物件上的自訂資料 | |
identities | identities, sso_identities | 使用者綁定的社交與 SSO 身分 | |
roles | roles | 使用者被指派的角色 (Roles) | ✅ |
urn:logto:scope:organizations | organizations | 使用者的組織 (Organizations) ID | ✅ |
urn:logto:scope:organizations | organization_data | 使用者的組織資料 | |
urn:logto:scope:organization_roles | organization_roles | 使用者的組織角色指派 (Organization roles) | ✅ |
在 Logto Console 中設定
若要在 ID 權杖中啟用擴充宣告：
- 前往 Console > 自訂 JWT。
- 開啟你希望納入 ID 權杖的宣告開關。
- 確保你的應用程式在驗證時請求對應的權限範圍。
相關資源
自訂存取權杖 (Custom access token)OpenID Connect Core - ID 權杖 (ID Token)