自定义 ID 令牌 (ID token)
介绍
ID 令牌 (ID token) 是由 OpenID Connect (OIDC) 协议定义的一种特殊类型的令牌。它作为由授权服务器（Logto）在用户成功认证 (Authentication) 后签发的身份声明，携带关于已认证用户身份的声明 (Claims)。
与用于访问受保护资源的 访问令牌 (Access tokens) 不同，ID 令牌 (ID token) 专为向客户端应用传递已认证用户身份而设计。它们是包含关于认证 (Authentication) 事件和已认证用户声明 (Claims) 的 JSON Web Token (JWT)。
ID 令牌 (ID token) 声明 (Claims) 的工作原理
在 Logto 中，ID 令牌 (ID token) 的声明 (Claims) 分为两类：
- 标准 OIDC 声明 (Claims)：由 OIDC 规范定义，这些声明 (Claims) 完全由认证 (Authentication) 时请求的权限 (Scopes) 决定。
- 扩展声明 (Claims)：Logto 扩展的声明 (Claims)，用于携带额外的身份信息，由双重条件模型（权限 (Scope) + 开关 (Toggle)）控制。
标准 OIDC 声明 (Claims)
标准声明 (Claims) 完全受 OIDC 规范约束。它们是否包含在 ID 令牌 (ID token) 中，仅取决于你的应用在认证 (Authentication) 时请求的权限 (Scopes)。Logto 不提供禁用或有选择地排除单个标准声明 (Claims) 的选项。
下表展示了标准权限 (Scopes) 与其对应声明 (Claims) 的映射关系：
| Scope | Claims |
|---|---|
openid | sub, auth_time, acr, amr（认证上下文声明 (Claims) 在会话中存在时包含；参见 提升认证 (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 权限 (Scopes)，ID 令牌 (ID token) 将包含来自 openid、profile 和 email 权限 (Scopes) 的所有声明 (Claims)。
扩展声明 (Claims)
除了标准 OIDC 声明 (Claims) 外，Logto 还扩展了携带 Logto 生态特有身份信息的声明 (Claims)。这些扩展声明 (Claims) 遵循双重条件模型，才能被包含在 ID 令牌 (ID token) 中：
- 权限 (Scope) 条件：应用在认证 (Authentication) 时必须请求对应的权限 (Scope)。
- 控制台开关：管理员需在 Logto Console 中启用该声明 (Claim) 在 ID 令牌 (ID token) 中的包含。
两项条件必须同时满足。权限 (Scope) 作为协议层的访问声明，开关 (Toggle) 作为产品层的暴露控制——两者职责明确且不可替代。
可用的扩展权限 (Scopes) 与声明 (Claims)
| Scope | Claims | 描述 | 默认包含 |
|---|---|---|---|
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 | 用户的组织 (Organizations) 数据 | |
urn:logto:scope:organization_roles | organization_roles | 用户的组织 (Organizations) 角色分配 | ✅ |
在 Logto Console 中配置
要在 ID 令牌 (ID token) 中启用扩展声明 (Claims)：
- 前往 控制台 > 自定义 JWT。
- 打开你希望包含在 ID 令牌 (ID token) 中的声明 (Claims) 开关。
- 确保你的应用在认证 (Authentication) 时请求了对应的权限 (Scopes)。
相关资源
自定义访问令牌 (Access token)OpenID Connect Core - ID Token