自定义 ID 令牌 (ID token)
简介
ID 令牌 (ID token) 是由 OpenID Connect (OIDC) 协议定义的一种特殊类型的令牌。它作为由授权 (Authorization) 服务器（Logto）在用户成功认证 (Authentication) 后签发的身份声明，携带关于已认证 (Authentication) 用户身份的声明 (Claims)。
与用于访问受保护资源的 访问令牌 (Access tokens) 不同，ID 令牌 (ID tokens) 专为向客户端应用程序传递已认证 (Authentication) 用户身份而设计。它们是包含关于认证 (Authentication) 事件和已认证 (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 |
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)。
- 控制台开关 (Toggle)：管理员必须通过 Logto Console 启用该声明 (Claim) 在 ID 令牌 (ID token) 中的包含。
这两个条件必须同时满足。权限 (Scope) 作为协议层的访问声明 (Claims)，而开关 (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) 角色 (Roles) 分配 | ✅ |
在 Logto Console 中配置
要在 ID 令牌 (ID token) 中启用扩展声明 (Claims)：
- 前往 控制台 > 自定义 JWT。
- 打开你希望包含在 ID 令牌 (ID token) 中的声明 (Claims) 开关。
- 确保你的应用在认证 (Authentication) 时请求了对应的权限 (Scopes)。
相关资源
自定义访问令牌 (Access token)OpenID Connect Core - ID Token