scope 与用户字段(claims)
全部 scope 的能力边界、userinfo 返回字段清单,以及按等级开放功能的 admin_level 用法。
更新于 2026-10-10
scope 与用户字段(claims)
本文列通行证支持的全部 scope、各 scope 对应的 userinfo 字段,以及 admin_level(权限等级)的用法。
一、scope 清单
| scope | 能力 |
|---|---|
openid |
签发 id_token(必选) |
profile |
用户名、昵称、头像、用户类型 |
email |
邮箱(仅主邮箱已验证时返回) |
realname |
实名姓名与实名状态 |
admin |
权限等级 admin_level(见下文第三节) |
offline_access |
额外发放 refresh_token(长期后台任务才需要) |
二、userinfo 字段
| 字段 | 说明 | 用途建议 |
|---|---|---|
sub |
通行证 UID,全局唯一且永不变 | 账号关联键(务必用它关联本地账号) |
preferred_username |
用户名 | 本地用户名兜底 |
nickname |
昵称 | 显示名 |
picture |
头像 URL | 显示头像 |
user_type |
用户类型(external / internal / developer) | 业务区分 |
email + email_verified |
邮箱(需 email scope) | 联系方式 |
realname + realname_status |
实名姓名 / 状态(需 realname scope) | 实名判断 |
admin_level |
权限等级 0-5(需 admin scope) | 按等级开放功能 |
三、权限等级 admin_level
申请 admin scope 后,id_token 与 userinfo 会多返回 admin_level:
| 值 | 含义 |
|---|---|
| 0 | 普通用户(默认) |
| 1-5 | 内部成员的管理权限等级(5 = owner,其余取管理员显式设置) |
- 不申请
adminscope 的平台不会收到该字段; - 第三方平台请求该 scope 时,用户同意页会明确列出「权限等级」项,用户同意后才回传;
- 该等级反映用户在通行证的管理权限,与消费会员等级无关。
典型用法:admin_level >= 2 才显示内部功能入口、>= 4 才开放运营操作等。