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,其余取管理员显式设置)
  • 不申请 admin scope 的平台不会收到该字段;
  • 第三方平台请求该 scope 时,用户同意页会明确列出「权限等级」项,用户同意后才回传;
  • 该等级反映用户在通行证的管理权限,与消费会员等级无关。

典型用法:admin_level >= 2 才显示内部功能入口、>= 4 才开放运营操作等。