自訂 ID 權杖 (ID token)
介紹
ID 權杖 (ID token) 是 OpenID Connect (OIDC) 協議定義的一種特殊權杖。它作為授權伺服器（Logto）在使用者成功驗證後簽發的身分聲明，攜帶經驗證使用者身分的宣告 (claims)。
與用於存取受保護資源的 存取權杖 (Access tokens) 不同，ID 權杖專為向用戶端應用程式傳遞經驗證使用者身分而設計。它們是 JSON Web Token (JWT)，包含有關驗證事件及經驗證使用者的宣告 (claims)。
ID 權杖宣告 (Claims) 的運作方式
在 Logto 中，ID 權杖宣告分為兩類：
- 標準 OIDC 宣告 (Standard OIDC claims)：由 OIDC 規範定義，完全取決於驗證時請求的權限範圍 (Scopes)。
- 擴充宣告 (Extended claims)：Logto 擴充的宣告，用於攜帶額外身分資訊，受 雙重條件模型（Scope + 切換開關） 控制。
標準 OIDC 宣告 (Standard OIDC claims)
標準宣告完全由 OIDC 規範管理。它們是否包含於 ID 權杖，僅取決於應用程式在驗證時請求的權限範圍 (Scopes)。Logto 不提供關閉或選擇性排除個別標準宣告的選項。
下表顯示標準權限範圍與其對應宣告的對應關係：
| 權限範圍 (Scope) | 宣告 (Claims) |
|---|---|
openid | sub, auth_time, acr, amr（驗證情境宣告於 session 存在時包含；詳見 進階驗證 (Step-up authentication)） |
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) | 宣告 (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 > Custom JWT。
- 開啟你希望包含於 ID 權杖的宣告切換開關。
- 確保你的應用程式在驗證時請求對應的權限範圍。
相關資源
自訂存取權杖 (Custom access token)OpenID Connect Core - ID Token