14 KiB
Hub 权限接口交互文档
本文档面向接入 Hub 的第三方业务系统。Hub 只提供当前用户的身份、组织、角色和权限查询;业务系统自行维护业务资源、资源归属和最终数据过滤。
1. 登录与认证
先获取验证码:
GET /auth/captcha
使用账号或邮箱、密码和验证码登录:
POST /auth/login
Content-Type: application/json
{"account":"zhangsan","password":"***","captcha_id":"...","captcha_answer":"..."}
email 可替代 account。登录成功后,响应 data 包含当前 user 和以下 tokens 字段:
{"access_token":"...","refresh_token":"...","expires_in":900,"token_type":"Bearer"}
业务系统使用 access_token 发起请求:
Authorization: Bearer <access_token>
需要独立校验 token 的场景,可调用 POST /api/v1/auth/token/verify,见第 10 节。接口从 JWT 的 sub 确定当前用户,不接受请求参数覆盖用户身份。client_credentials 或没有用户 sub 的 token 不能调用用户授权接口。Hub 会实时检查用户状态和 token 签名;停用用户后旧 JWT 也会返回 token 失效,不需要撤销 JWT 黑名单。
注册审核可以先跳过组织和角色分配。此类用户可以调用 /api/v1/auth/me 获取身份,organization_id 为 0;角色、权限和数据范围查询仍要求当前用户具备有效授权上下文,未分配启用组织时会返回 403001。分配组织和角色后立即生效。
2. 统一响应
所有 /api/v1/auth 接口使用以下结构:
{"code":"200","data":{},"message":"success"}
错误码如下:
| HTTP | code | 含义 |
|---|---|---|
| 200 | 200 |
成功 |
| 400 | 400001 |
参数、状态或关系不合法 |
| 401 | 401001 |
token 缺失、过期或已失效 |
| 403 | 403001 |
当前用户无权限或身份数据无效 |
| 404 | 404001 |
目标资源不存在 |
| 500 | 500001 |
服务暂不可用 |
失败时 data 为 null。业务系统应优先判断 code,不要依赖错误文案。
3. 推荐调用流程
业务系统收到用户 token 后:
- 调用
GET /api/v1/auth/me获取稳定用户标识和当前组织。 - 调用
GET /api/v1/auth/me/roles获取当前有效角色。 - 调用
GET /api/v1/auth/me/permissions?application_id=<业务应用>获取该用户当前有效权限。 - 调用
GET /api/v1/auth/me/data-scope获取角色合并后的有效数据范围和组织/用户集合。 - 在自己的数据库查询中按权限 code 和
data_scope过滤业务资源。 - 记录返回的
permission_version;发现版本变化或本地缓存过期时重新查询。 - 需要镜像 Hub 组织和人员时调用
GET /api/v1/auth/directory,需要按调用者数据权限过滤人员时调用GET /api/v1/auth/directory/scoped,见第 11 节。
接口不分页,并返回 Cache-Control: no-store、Pragma: no-cache。业务系统可自行做短期内存缓存,但必须负责失效。
4. 当前身份
GET /api/v1/auth/me
示例:
{
"code":"200",
"data":{
"sub":"42",
"preferred_username":"zhangsan",
"name":"张三",
"organization_id":3
},
"message":"success"
}
5. 查询当前角色
GET /api/v1/auth/me/roles
示例:
{
"code":"200",
"data":{"roles":[{"role_id":2,"code":"orders-reader","name":"订单查询员","data_scope":"ORG","status":1}]},
"message":"success"
}
返回空 roles 表示用户尚未绑定有效角色。角色用于前端功能分流或展示;业务接口仍应依据下一节的权限 code 和数据范围进行处理。
6. 查询权限
GET /api/v1/auth/me/permissions?application_id=orders
返回的权限项只有权限目录字段:
{
"code":"200",
"data":{
"permissions":[
{"permission_id":18,"application_id":"orders","type":"api","code":"order.read","name":"查询订单","status":1}
],
"permission_version":8
},
"message":"success"
}
权限目录的 application_id + type + code 是稳定唯一标识。type 常用值为 api、menu、plugin。权限目录不定义数据范围;数据范围只配置在角色上,用户拥有多个角色时按 SELF < ORG < ORG_AND_CHILDREN < ALL 取最大范围。
7. 查询数据范围
GET /api/v1/auth/me/data-scope
示例:
{
"code":"200",
"data":{
"users":[{"user_id":42,"display_name":"张三","organization_id":3}],
"organizations":[{"organization_id":3,"name":"销售部","path":"/1/3/"}],
"data_scope":"ORG_AND_CHILDREN",
"permission_version":8
},
"message":"success"
}
没有有效角色时返回空 users、空 organizations 和 data_scope: null。业务系统不能把这些用户/组织对象当作自己的业务资源详情,必须继续校验业务资源的 owner 或 organization 字段。
管理员如需查询指定用户,可调用 GET /api/v1/auth/admin/users/{id}/data-scope;普通业务系统只应使用 /me/*,不要让客户端传入用户 ID 查询他人权限。
8. 管理配置接口
管理员 Bearer token 可调用以下不分页目录接口:
GET /api/v1/auth/admin/organizations
GET /api/v1/auth/admin/roles
GET /api/v1/auth/admin/permissions?application_id=orders
GET /api/v1/auth/admin/users/{id}/roles
GET /api/v1/auth/admin/roles/{id}/permissions
业务系统登记权限后,由管理员将权限绑定到角色,再将角色绑定到用户:
POST /api/v1/auth/admin/permissions
{"application_id":"orders","type":"api","code":"order.read","name":"查询订单"}
POST /api/v1/auth/admin/roles/{role_id}/permissions/{permission_id}
POST /api/v1/auth/admin/users/{user_id}/roles/{role_id}
PUT /api/v1/auth/admin/users/{user_id}/organization
{"organization_id":3}
角色创建或编辑时配置 data_scope:
{"code":"orders-reader","name":"订单查询员","data_scope":"ORG"}
权限和角色关系、用户和角色关系可重复提交;重复绑定是幂等成功,不会重复记录或递增版本。权限 code、角色 code 和组织 code 一旦被业务系统使用,不应修改;展示名称可通过管理接口编辑。
9. 应用侧判定示例
业务后端收到 order.read 和 ORG 后,应先检查权限 code,再把当前用户组织作为业务表过滤条件:
允许调用 = permissions 包含 orders/api/order.read
数据条件 = order.organization_id = currentUser.organization_id
ALL、组织树和本人范围的具体 SQL 由业务系统根据自己的组织字段实现。Hub 不访问第三方业务数据库,也不代替业务系统执行资源级授权。
10. 验证 token 是否有效
其它系统统一使用 Hub 登录获取 token,再调用本接口校验 token 是否仍然可用。本接口不校验调用方权限(被校验的 token 本身就是入参),无 token 也不会返回 401,统一返回 HTTP 200 并由 data.active 表达结果,调用方只需判断 active。
POST /api/v1/auth/token/verify
Authorization: Bearer <access_token>
token 也可以放在请求体里,便于网关或批处理场景传递:
POST /api/v1/auth/token/verify
Content-Type: application/json
{"token":"<access_token>"}
取值优先级为请求体 token、Authorization: Bearer、Hub 会话 Cookie dsh_hub_token。token 有效时:
{"code":"200","message":"success","data":{"active":true,"user_id":12,"account":"zhangsan","email":"zhangsan@example.com","role":"member","issued_at":"2026-09-11T02:00:00Z","expires_at":"2026-09-11T02:15:00Z"}}
token 不可用时 active 为 false,reason 只可能是以下三种:
| reason | 含义 | 调用方处理 |
|---|---|---|
missing_token |
请求既没有请求体 token,也没有 Bearer 头和会话 Cookie | 提示重新登录 |
invalid_token |
签名错误、已过期、格式非法或非用户 token | 提示重新登录 |
token_user_inactive |
token 本身有效,但对应用户已删除或已停用 | 强制下线并清理本地会话 |
invalid_token 刻意不区分“签名不对”和“用户不存在”,本接口不能用于探测账号是否存在。只有在查询用户时发生存储故障(例如数据库不可用)才返回 500 和 500001,此时调用方应保留本地会话并重试,不要强制用户重新登录。停用用户后旧 JWT 会立即返回 token_user_inactive,无需撤销名单。业务系统应在自己的会话校验里调用本接口,或使用带缓存的校验(建议缓存不超过 access token 剩余有效期),并始终保留接口返回的失效语义。
11. 全量组织树与全量人员
Hub 提供两个口径的组织人员导出接口,返回结构完全一致,只有人员可见范围不同:
| 接口 | 校验 | 人员范围 | 适用调用方 |
|---|---|---|---|
GET /api/v1/auth/directory |
只校验 token 是否有效,不校验角色和数据权限 | 全量人员 | 受信系统集成,镜像 Hub 的组织和花名册 |
GET /api/v1/auth/directory/scoped |
校验 token 并按调用者数据权限过滤 | 仅调用者数据权限内的人员 | 需要站在最终用户视角展示组织和人员的系统 |
两个接口的组织树都是完整的:scoped 只会隐藏组织下的人员,不会删掉调用者无权限的组织,因此只有 A 部门权限的账号依然能看到 A 的父级和兄弟组织,无可见人员的组织返回空 members 数组。
集成系统用任意有效 Bearer token 调用全量接口,一次拿到完整组织树以及挂在组织下的全量人员:
GET /api/v1/auth/directory
Authorization: Bearer <access_token>
| 查询参数 | 默认值 | 说明 |
|---|---|---|
include_disabled |
false |
置为 true 时同时输出停用组织及其子树,并保留其真实 status |
include_disabled_users |
false |
置为 true 时人员清单同时包含已停用用户,镜像系统据此同步下线账号 |
member_limit |
2000 |
本次导出的人员条数上限,取值 1 至 5000,超限或非法返回 400001。组织树与扁平清单来自同一批人员,截断时两者同时不完整 |
响应结构如下,organizations 是嵌套树,users 是同一批人员的扁平清单:
{"code":"200","message":"success","data":{
"organizations":[
{"organization_id":1,"code":"root","name":"总部","path":"/1/","status":1,"member_count":1,
"members":[{"user_id":12,"account":"zhangsan","display_name":"张三","organization_id":1,"status":1}],
"children":[{"organization_id":2,"code":"sales","name":"销售部","parent_id":1,"path":"/1/2/","status":1,"member_count":0,"members":[],"children":[]}]}
],
"users":[{"user_id":12,"account":"zhangsan","display_name":"张三","organization_id":1,"status":1}],
"total_users":1,"returned_users":1,"member_limit":2000,"truncated":false,"permission_version":37
}}
status 为 1 表示启用,其余值表示停用等待审核状态,镜像系统据此启用或下线本地账号。调用方需要按以下约定处理:
- 默认只导出启用用户;
include_disabled_users=true时人员清单会同时返回已停用用户,镜像系统按status下线本地账号,total_users、returned_users和truncated都按同一状态过滤口径统计。scoped接口忽略该参数。 - 用户所属组织被停用、组织不存在或未分配组织时,该用户挂在合成节点
organization_id为0、code为unassigned的节点上,并作为最后一个根节点返回,保证全量导出不会丢人。扁平清单users里保留用户真实存储的organization_id,镜像方按users落库更稳妥。 total_users是启用用户的总数(不受member_limit影响),returned_users是本次返回数量,truncated为true说明人员清单被member_limit截断,此时组织树里的members同样不完整,只能用于探查规模;正式同步应调大member_limit,且不要按截断结果删除本地人员。members、children恒为数组而非null;member_count只统计直接挂在该组织的人员,不含子组织。- 深度上限为 64 层,组织层级成环时返回
500001而不是静默丢弃数据;出现该错误应先修复组织父子关系。 - 组织或人员发生任何变更都会递增
permission_version,镜像系统建议定时拉取并在版本未变化时跳过写入。
GET /api/v1/auth/directory 只要求 token 有效,不再要求管理员角色,token 无效或未登录返回 401001,因此调用方务必只在服务端到服务端方向使用,不要把该接口的访问凭证下发到浏览器或移动端。需要“按人给数据”时使用 GET /api/v1/auth/directory/scoped,该接口沿用数据权限校验:账号未分配组织或数据权限不可用时返回 403001,并且忽略 include_disabled_users(数据权限只覆盖启用用户)。
按数据权限导出时 total_users、returned_users、truncated 以及各组织的 member_count 都只统计调用者可见的人员,member_limit 同样作用在过滤之后的人员上。该接口需要先读出人员再按数据权限过滤,单次最多读取 5000 条用户记录:租户用户总量超过 5000 时 truncated 会是 true 且 total_users 只代表本次扫描到的可见人员,此时不要按结果删除本地人员,应改用全量接口或调低同步粒度。两个接口都携带 Cache-Control: no-store,并分别记录审计日志 rbac.directory.export 与 rbac.directory.scoped.export。