IdentityServer4中API资源与API Scope的用户声明差异及示例解析
先直接给你核心结论：API资源上配置的用户声明是「所有访问该API的客户端，无论请求哪个Scope都会拿到的通用基础信息」；而API Scope上配置的声明是「只有请求了这个特定Scope的客户端，才会额外获得的、和该Scope对应权限/场景相关的细分信息」。
结合你提到的两个场景来具体拆解：
场景1：GitHub API 示例
假设我们定义一个名为github_api的API资源，以及两个Scope：repo（仓库访问权限）、gist（Gist访问权限）。
API资源（github_api）上的用户声明
这里配置的是所有GitHub API接口都需要的通用用户信息，比如：
sub：用户的唯一标识（IdentityServer默认会包含，但如果需要显式指定也可以加）email：用户的注册邮箱github_username：用户的GitHub用户名
这些声明的作用是：不管客户端是请求repo还是gist，GitHub的所有接口都需要知道「是谁在请求」——比如你访问Gist接口时需要验证用户身份，访问仓库接口时也一样，这些信息是跨Scope通用的。
API Scope上的用户声明
针对repo Scope
配置和仓库权限/信息相关的细分声明，比如：
repo_access_level：用户对仓库的权限等级（比如read-only/read-write/admin）private_repo_count：用户拥有的私有仓库数量org_member_status：用户是否是某个组织的成员
只有当客户端请求了repo这个Scope时，IdentityServer才会把这些声明放进Access Token里。因为这些信息只有在访问仓库相关接口时才有用——比如当用户尝试修改仓库设置时，API可以通过repo_access_level判断是否有足够权限；而如果客户端只请求gist Scope，这些仓库相关的声明就不会出现在Token里，既减少了Token体积，也避免了不必要的信息泄露。
针对gist Scope
配置和Gist相关的细分声明，比如：
gist_public_count：用户的公开Gist数量gist_private_enabled：用户是否开启了私有Gist功能
同样，只有请求gist Scope的客户端才会拿到这些声明，用于Gist相关接口的权限或逻辑判断。
场景2：通用批量导入API 示例
定义bulk_import_api作为API资源，两个Scope：import_job:view（查看导入任务）、import_job:control（启停/删除导入任务）。
API资源（bulk_import_api）上的用户声明
配置所有导入操作都需要的通用信息：
sub：用户唯一标识tenant_id：用户所属的租户ID（因为导入数据通常是按租户隔离的）email：用户邮箱（用于任务完成时发送通知）
这些信息是所有导入接口的基础——比如查看任务列表时需要筛选当前租户的任务，启动任务时也要关联到租户，所以不管请求哪个Scope，这些声明都会被包含在Token里。
API Scope上的用户声明
针对import_job:view Scope
配置和查看任务相关的细分声明：
import_job_view_limit：用户最多能查看的历史任务数量import_job_detail_access：是否允许查看任务的详细日志
只有请求这个Scope的客户端（比如普通用户的查询工具）会拿到这些声明，API可以根据import_job_view_limit限制用户的查询范围。
针对import_job:control Scope
配置和任务控制相关的细分声明：
import_job_max_concurrent：用户最多能同时运行的导入任务数import_job_approval_required：启动任务是否需要管理员审批import_job_delete_permission：是否允许删除已完成的任务
只有请求这个Scope的客户端（比如管理员的任务管理后台）会拿到这些声明。当用户尝试启动任务时，API会检查import_job_max_concurrent判断是否超过上限；如果import_job_approval_required为true，则会触发审批流程。
实际应用中的逻辑总结
- Token内容组合：当客户端请求多个Scope时，最终的Access Token会包含「API资源的所有通用声明」 + 「所有请求的Scope对应的细分声明」。
- 安全与效率：用Scope来控制细分声明的发放，避免把所有用户信息都塞进Token里——既减少了Token的大小，也降低了敏感信息被不必要暴露的风险。
- API权限控制：API可以同时依赖Scope和声明做权限判断：先通过Scope判断用户是否有访问某个接口的权限，再通过对应的声明做更细粒度的控制（比如限制并发数、权限等级）。
内容的提问来源于stack exchange，提问作者alastairs
