unis-oa/third-party-integration.md

36 KiB
Raw Permalink Blame History

dsh-hub 统一门户 第三方系统对接指南

适用范围:需要接入 dsh-hub 统一门户的外部业务系统(OA、HR、业务后台、运维平台)的后端与运维人员,覆盖免登跳转、票据换取身份、用户与组织同步、企业微信上游语义、错误码与排错。契约依据为 hub-server 当前分支代码,接口路径、字段名、鉴权头与默认值均以代码为准。机器可读契约见仓库内 docs/openapi.yaml,它与 hub-server 内嵌副本按字节一致(有测试保证),运行中的实例在 /swagger/index.html 提供同一份在线文档。

最后更新:2026-09-28

1 接入总览

hub 在接入关系中同时扮演三个角色:统一用户与组织主数据源(下游只读消费,不在下游另建人员组织)、统一认证入口(用户在 hub 登录后从门户进入下游)、上游身份代理方(企业微信等上游只对接 hub,上游令牌绝不下发,下游只看到 hub 签发的 sub)。

1.1 免登时序

用户浏览器                hub                     下游后端
   | 已登录门户             |                         |
   | GET /api/v1/auth/apps  |                         |
   |----------------------->| 返回可见应用             |
   | POST /api/v1/auth/apps/{code}/launch             |
   |----------------------->| 签发一次性 ticket        |
   | 302 Location: launch_url?ticket=...&state=...    |
   |<-----------------------|                        |
   | 携带 ticket 落到下游页面                          |
   |                        |  POST /api/v1/auth/tickets/verify
   |                        |  X-Integration-Key ---->| 校验并消费票据
   |                        |  <--------------------- | active + sub + account
   | 下游会话 Cookie        |                         | 建/绑本地会话

票据只在下游后端校验这一步出现,浏览器不参与校验。下游以 sub 建立或绑定本地用户,再签发自身的会话 Cookie。

1.2 凭证矩阵

凭证 位置 可访问接口 来源
X-Integration-Key 请求头 仅 POST /api/v1/auth/tickets/verify 管理端注册或轮换应用时下发的应用密钥
X-Directory-Key 请求头 GET /api/v1/auth/directory、GET /api/v1/auth/directory/changes 服务端配置 HUB_DIRECTORY_KEYS
Authorization: Bearer <access_token> 或 Cookie dsh_hub_token 请求头 / Cookie GET /api/v1/auth/apps、POST /api/v1/auth/apps/{code}/launch、全部 /api/v1/auth/admin/** 用户登录换取
  • 三类凭证互不通用:目录密钥不能免登或查应用列表,用户令牌不能调用票据校验,应用密钥不能读目录。
  • HUB_DIRECTORY_KEYS 格式为 标签:密钥 或裸密钥,逗号分隔多条;生产环境每条整串长度不得小于 40 字符,密钥用 openssl rand -hex 32 生成。示例为占位符,不可直接使用:HUB_DIRECTORY_KEYS=oa:<64位十六进制随机串>。
  • HUB_DIRECTORY_KEYS 中的密钥同时是应急 bootstrap 通道:调用票据校验时额外携带 app_code 即可用目录密钥换取身份。日常对接使用应用密钥,不需要 app_code。
  • CORS 允许头只有 Authorization, Content-Type, X-Directory-Key,X-Integration-Key 不在其中,浏览器无法直接调用票据校验。

1.3 响应信封

/api/v1/auth/** 统一返回 {"code": "200", "data": {}, "message": "success"}。成功恒为 HTTP 200、code 为字符串 "200";失败时 HTTP 状态码与 code 同步变化且 data 为 null。判定成功以 code == "200" 为准,不要依赖 message 中文文案。

1.4 统一登录入口

登录只发生在 hub,下游系统不再自己认人,也不再有第二种登录方式。

  • 账号来源只有两个:管理员在 hub 创建、企业微信通讯录同步。公开自助注册默认关闭(HUB_SELF_REGISTRATION_ENABLED=false),hub 登录页仍保留「注册」标签,但提交后由后端以 403 registration_disabled 拒绝。
  • 登录成功后固定先落在统一门户页,用户看到自己有权限的应用卡片;点击卡片才签发一次性 ticket 并 302 跳到下游,这就是「统一跳转」。没有 console.my_apps 权限的用户落到自己有权限的第一个视图,完全没有 hub 菜单权限的用户落到个人智能体工作区。
  • 下游侧要求:撤掉本系统的账号密码登录、注册、找回密码入口,只保留「退出」。访问受保护页面且本地无会话时 302 回 hub 站点首页,由用户重新从门户点进来。
  • 一期不支持「登录后回跳来源系统」:hub 前端不解析 redirect 之类的查询参数,下游不能指望未登录跳回 hub 后自动回到原页面,只能回到 hub 首页。
  • 票据缺失、过期或校验返回 active:false 时统一回到 hub,不允许回落到本地密码登录或复用旧会话。

2 管理员配置项

应用注册由 hub 管理员完成,管理接口(/api/v1/auth/admin/**)要求当前账号具备 RBAC admin 角色,否则 403 403001。

方法 路径 用途
GET / POST /api/v1/auth/admin/integrations 列出全部应用(含停用)/ 注册应用并下发密钥
GET / PUT / DELETE /api/v1/auth/admin/integrations/{id} 查看 / 整体覆盖保存 / 删除应用
PUT /api/v1/auth/admin/integrations/{id}/status 启用或停用,请求体 {"status": 1}
POST /api/v1/auth/admin/integrations/{id}/secret/rotate 轮换密钥

2.1 应用字段

字段 类型 必填 默认 说明
code string 是 - 应用编码,即跳转路径里的 {code}。只允许小写字母、数字、-、_、.,最长 64;保存前转小写去空格,全局唯一,重复报 400 400001(应用编码已存在)
name string 是 - 应用显示名
launch_url string 是 - 免登落地地址,必须以 http:// 或 https:// 开头
home_url string 否 空 备用展示地址,只保存与回显;免登跳转一律使用 launch_url,该字段不参与票据地址拼接
description / icon_url string 否 空 描述与图标
redirect_uris string 数组 否 空数组 回调地址白名单,每项必须以 http:// 或 https:// 开头,精确匹配
sso_mode string 否 ticket 只接受 ticket 与 none;oidc 为二期预留,保存会被拒绝。none 目前只是门户语义标记,签发行为不区分,以实现为准
ticket_ttl_seconds int 否 30 票据有效期秒数,小于等于 0 取 30,大于 300 截断为 300
status / visible int 否 1 1 启用 / 门户可见,0 停用 / 隐藏,其它值收敛到 0 或 1
role_ids int64 数组 否 空数组 允许在门户看到并免登进入该应用的角色,用户命中其中任意一个即可(并集)。创建与 PUT 都是整体覆盖;含不存在的角色报 400 400001(授权角色不存在)。空数组表示对所有人隐藏,管理员也不例外

PUT 是整体覆盖保存,请求体缺省的字段按默认值写入;code 与密钥不在该接口修改。其余响应字段:role_ids(管理员接口始终回显,GET /auth/apps 一律不回显,避免向普通用户泄露权限结构)、app_id、secret_prefix、secret_configured、secret_rotated_at、previous_valid_until、last_used_at、created_by、created_at、updated_at。删除响应 data 为 {"deleted": true}。

2.2 密钥

  • 密钥为 32 字节随机数的十六进制表示,长度 64 字符。
  • 明文只在创建和轮换的响应 data.secret 中出现一次,伴随 secret_shown_once: true;hub 不保留可还原的明文,库中存去空格后的 SHA-256(密钥),对外只回显 secret_prefix(前 8 字符)与 secret_configured。
  • 密钥比对为常数时间比较。应用停用后密钥立即失效(密钥查询只匹配启用状态的应用)。

2.3 已有环境升级

  • 统一门户与角色可见性依赖这些表:integration_apps、app_launch_tickets、integration_app_roles,以及同步侧的 external_identities、wecom_configs、wecom_sync_claims、wecom_sync_runs、directory_changes。hub-server/schema.sql 全部使用 CREATE TABLE IF NOT EXISTS,对已有库可以整体重新执行,不会重建或清空数据。
  • 执行前先确认目标库:schema.sql 开头写死了 CREATE DATABASE IF NOT EXISTS nanobot; 和 USE nanobot;,而 HUB_MYSQL_DSN 一般指向 dsh_hub。整文件执行时请删掉这两行或改成实际使用的库,否则新表会落到 nanobot 库,hub 启动后报表不存在。
  • 可见性判定是默认拒绝且不豁免管理员。升级后存量应用在 integration_app_roles 里没有记录,等于对所有人(含管理员)都不可见,因此上线时必须先补授权。例如统一放开 member 角色:
INSERT IGNORE INTO integration_app_roles (app_id, role_id, created_at)
SELECT a.id, r.id, UTC_TIMESTAMP(3)
FROM integration_apps a
CROSS JOIN roles r
WHERE r.code = 'member';
  • 核对每个应用实际拿到的授权角色数,结果为 0 的应用谁都看不到:
SELECT a.code, COUNT(iar.role_id) AS granted_roles
FROM integration_apps a
LEFT JOIN integration_app_roles iar ON iar.app_id = a.id
GROUP BY a.id, a.code

3 免登跳转

3.1 查询可见应用

curl -sS -H "Authorization: Bearer $TOKEN" https://hub.example.com/api/v1/auth/apps

需要用户登录态。这个接口就是统一门户落地页的数据源,判定条件三条同时成立:应用 status=1、visible=1、且应用的授权角色与用户当前有效角色取并集命中任意一个。未授权任何角色的应用对所有人隐藏,管理员不因角色特权放行;角色一律实时读取,不进令牌,管理员调整授权后下一次请求立即生效。

{"code": "200", "data": {"items": [{"app_id": 1, "code": "oa", "name": "办公自动化",
  "launch_url": "https://oa.example.com/sso/hub", "home_url": "https://oa.example.com/",
  "sso_mode": "ticket", "ticket_ttl_seconds": 30, "secret_prefix": "9f2c1a70",
  "secret_configured": true, "status": 1, "visible": 1,
  "redirect_uris": ["https://oa.example.com/sso/hub"]}], "total": 1}, "message": "success"}

3.2 发起跳转

curl -sS -X POST https://hub.example.com/api/v1/auth/apps/oa/launch \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"state":"b7f1c2","redirect_uri":"https://oa.example.com/sso/hub"}'
{"code": "200", "data": {"redirect_url": "https://oa.example.com/sso/hub?ticket=6a1f...&state=b7f1c2",
  "ticket": "6a1f...", "expires_at": "2026-09-24T10:00:30Z", "app_code": "oa"}, "message": "success"}
  • 路径 {code} 不区分大小写,hub 转小写后查找;不存在返回 404 404001,已停用返回 403 403001(应用已停用)。
  • 免登入口独立鉴权,与门户列表同一判定:用户没有命中该应用的任何一个授权角色时返回 403 403001(无权访问该应用),绕过门户直接调用同样拿不到票据。
  • 请求体两个字段都可省略。传 redirect_uri 时必须与 redirect_uris 某一项完全相等,否则 400 400001(回调地址未在应用中登记);不传时落地地址为 launch_url。
  • state 原样回传,既拼进 redirect_url,也在票据校验响应里原样返回。
  • 拼接规则:目标地址无 ? 用 ?,已有 ? 用 &;ticket 与 state 做 URL 转义;state 为空不拼。
  • 加查询参数 ?redirect=true(大小写不敏感)时直接返回 302 Found,Location 即上述地址,适合门户前端整页跳转。
  • 有效期取应用的 ticket_ttl_seconds,未配置时为 30 秒。每次成功跳转刷新 last_used_at 并写审计 portal.app.launch。

4 票据校验(服务端到服务端)

4.1 请求

curl -sS -X POST https://hub.example.com/api/v1/auth/tickets/verify \
  -H 'X-Integration-Key: <应用密钥明文>' -H 'Content-Type: application/json' \
  -d '{"ticket":"6a1f..."}'
项 位置 必填 说明
X-Integration-Key 请求头 是 应用密钥明文,即创建或轮换接口返回过的那一次明文
ticket body 是 跳转拿到的票据原值,64 位十六进制;去空格后为空返回 400 400001
app_code body 否 仅在使用 HUB_DIRECTORY_KEYS 中的 bootstrap 密钥时必填;用应用密钥时无需传,同时传时二者必须对应同一应用

该接口不校验用户登录态,也不读取 Authorization,密钥正确即可调用。

4.2 校验成功

{"code": "200", "data": {"active": true, "sub": "10086", "account": "zhangsan", "display_name": "张三",
  "email": "zhangsan@example.com", "app_code": "oa", "issued_at": "2026-09-24T10:00:00Z",
  "expires_at": "2026-09-24T10:00:30Z", "state": "b7f1c2"}, "message": "success"}
字段 类型 说明
active bool 恒为 true
sub string hub 用户 ID 的十进制字符串,下游以此作为用户唯一键
account / display_name / email string 登录账号(hub 权威字段,下游只读)、姓名、邮箱(可能为空字符串)
app_code string 票据所属应用编码,与自身 code 比对可防串号
issued_at / expires_at time 票据签发与过期时间,UTC,RFC3339
state string 发起跳转时传入的 state 原样回传,未传为空字符串

下游建会话的最小字段集为 sub、account、display_name。角色与权限由下游自行维护,hub 不下发角色。

4.3 校验失败

票据类失败一律 HTTP 200、code 为 "200",由 active: false 与 reason 表达,响应 data 只含 active、reason、app_code。

reason 语义 下游处理
ticket_invalid 票据不存在或已被消费 拒绝本次登录,提示重新从门户进入
ticket_audience_mismatch 票据属于其它应用 拒绝并告警,通常是密钥配错应用或 app_code 传错
ticket_expired 超过 expires_at 拒绝,提示用户在门户重新点击应用
user_inactive 用户不存在或 status 不为 1 按用户已停用处理,不要回落到本地旧会话

4.4 一次性消费

  • 校验入口对票据执行“先查询、立即删除”,删除发生在受众与有效期判定之前,因此同一个 ticket 第二次调用必定 ticket_invalid,即使第一次因受众不匹配或过期失败。
  • 禁止对票据校验自动重试。超时后无法判断 hub 是否已消费,正确做法是丢弃当前票据,让用户重新发起跳转。
  • 票据值不入库、不写日志、不进前端埋点与 Referer,不通过 <img>、<script> 等第三方资源传递。
  • 落地页拿到票据后立即由后端消费,成功后改用自身会话 Cookie 承接,并用 history.replaceState 清掉地址栏票据。下游应对 expires_at 做二次校验,时钟以 NTP 校准。

4.5 密钥层面的错误

HTTP code message 触发条件
400 400001 请求参数无效 请求体非法 JSON 或 ticket 为空
401 401001 缺少集成密钥 既无 X-Integration-Key 也无 app_code
401 401001 集成密钥无效 密钥不属于任何启用中的应用,也不是 bootstrap 密钥;应用被停用同样落在这里
403 403001 密钥与应用的对应关系不正确 app_code 与密钥所属应用不同
404 404001 应用不存在 使用 bootstrap 密钥且 app_code 无对应应用

5 安全要求

项 要求
传输 生产环境 hub 基地址、launch_url、redirect_uris 全部 HTTPS。代码允许 http:// 前缀,仅用于本地联调
密钥保管 hub 侧只存 SHA-256(密钥)。下游按同等保密级别存放,走密钥管理服务或环境变量,不进代码仓库与前端产物
密钥轮换 POST /api/v1/auth/admin/integrations/{id}/secret/rotate 后新旧密钥同时可用,旧密钥到期时间由响应 previous_valid_until 给出,宽限期 24 小时。切换前先在新密钥下验证一次连通性
密钥范围 X-Integration-Key 只能调用票据校验,不能读目录、不能调管理接口
state 校验 下游生成随机 state 并存服务端会话,回调时必须与校验响应的 state 精确比对,不一致直接拒绝,用于防会话固定与注入
身份映射 只以 sub 建立映射,禁止用 display_name 或 email 自动合并账号

密钥泄露处置顺序:先轮换(旧密钥进入 24 小时宽限期后自动失效);若确认被主动利用,直接 PUT /api/v1/auth/admin/integrations/{id}/status 置 {"status": 0},密钥与跳转同时失效;随后排查该应用的 portal.ticket.verify 审计(含 warning 级别)与下游登录日志。

6 用户与组织同步

同步方向单向:hub 是权威源,下游只读,不得回写人员与组织。

6.1 全量目录

curl -sS -H 'X-Directory-Key: <目录密钥>' \
  'https://hub.example.com/api/v1/auth/directory?include_disabled=true&include_disabled_users=true'

鉴权二选一:X-Directory-Key 或用户登录态。携带了 X-Directory-Key 但不认识时直接 401 401001,不会回落到令牌。两条路径都返回完整目录,不按角色或数据权限裁剪;按数据权限裁剪的是 GET /api/v1/auth/directory/scoped(仅用户登录态,不适合镜像场景)。

查询参数 默认 说明
tree false false 时组织与用户是两个扁平列表,由调用方按 organization_id 关联;true 时组织递归嵌套 children,且每个节点内重复展开 members
include_disabled false 是否输出停用组织;注意它同时决定不可达子树是否输出:父组织停用后,状态仍为 1 的子组织在默认导出里也会一起消失,镜像场景必须置 true
include_disabled_users false 是否输出停用用户,默认只有 status=1;scoped 接口忽略该参数
member_limit 2000 花名册条数,取值 1-5000,越界或非数字返回 400 400001;该接口无分页参数
{"code": "200", "data": {"organizations": [{"organization_id": 1, "code": "root", "name": "总公司",
  "path": "/1/", "status": 1, "created_at": "2026-01-05T02:00:00Z",
  "member_count": 120, "direct_member_count": 3, "members": [], "children": []}],
 "users": [{"user_id": 10086, "account": "zhangsan", "display_name": "张三",
  "email": "zhangsan@example.com", "organization_id": 12, "status": 1}],
 "total_users": 500, "returned_users": 500, "member_limit": 2000, "truncated": false,
 "permission_version": 17}, "message": "success"}
字段 说明
organizations[].organization_id / code / name 组织主键、编码(企业微信同步生成的是 wecom-<部门ID>)、名称;short_name 为空时省略
organizations[].parent_id 上级组织 ID,根节点为 0 且字段省略
organizations[].path 祖先链,形如 /1/12/,判断父子与子孙关系以此为准
organizations[].status 0 停用、1 启用
member_count / direct_member_count 本级与全部子孙累计人数 / 只挂本级的人数
users[].user_id 用户 ID,等同票据校验的 sub(数值形式)
users[].status 0 停用、1 正常、2 待审核、3 已拒绝
users[].organization_id 主组织 ID;无有效组织的用户归入合成节点 organization_id=0、code=unassigned
total_users / returned_users / truncated 命中条件总数 / 本次返回数 / 是否被 member_limit 截断,截断时须提高上限重拉
permission_version 权限数据版本号,仅在影响鉴权结果的写入时递增,不能当目录游标

空集合输出 [] 而非 null。多组织归属只导出主组织,下游按单主组织建模。

6.2 增量变更流

curl -sS -H 'X-Directory-Key: <目录密钥>' 'https://hub.example.com/api/v1/auth/directory/changes?since=1000&limit=200'
查询参数 默认 说明
since 0 游标,排他语义,只返回 seq > since;负数按 0
limit 50 单批条数,小于等于 0 取 50,大于 500 收敛为 500
{"code": "200", "data": {"cursor": 1042, "oldest_seq": 1, "newest_seq": 1042, "has_more": false,
 "changes": [{"seq": 1042, "entity": "user", "entity_id": 10086, "op": "upsert", "source": "wecom",
   "occurred_at": "2026-09-24T02:00:00Z",
   "data": {"id": 10086, "account": "zhangsan", "display_name": "张三", "organization_id": 12,
            "role": "user", "status": 1, "created_at": "2026-01-05T02:00:00Z"}}]},
 "message": "success"}

游标语义:cursor 是本批最后一条的 seq,本批无变更时等于传入的 since;has_more 为 true 时用同一个 cursor 继续拉取直到 false;since 小于 oldest_seq 说明中间流水已不可靠,必须回到全量。变更写入是尽力而为,写失败只记日志不影响业务请求,增量流不能作为唯一可信来源。

entity 取 user 或 organization,op 取 upsert 或 delete,source 取 hub(管理端人工维护)或 wecom(同步写入),delete 事件不带 data。data 键名随来源变化,先按 source 与 entity 分支再取值。

触发写路径 entity / op / source data
新增或整体修改组织 organization / upsert / hub 完整组织对象(键名同全量目录)
改组织状态 / 移动组织 organization / upsert / hub {"id": 12, "status": 0} / {"id": 12, "parent_id": 3}
同步写入组织 organization / upsert / wecom {"organization_id": 12, "code": "wecom-12", "name": "研发部", "parent_id": 1, "status": 1}
调整用户组织 / 注册审核通过 user / upsert / hub {"id": 10086, "organization_id": 12} / {"id": 10086, "status": 1}
待认领记录绑定已有账号 user / upsert / hub 完整用户对象 id、account、email、display_name、avatar_url、organization_id、role、status、created_at
同步写入人员 user / upsert / wecom 完整用户对象,同上
管理员删除用户 user / delete / hub 无

6.3 推荐同步流程

  1. 首次全量:GET /api/v1/auth/directory?include_disabled=true&include_disabled_users=true,按 user_id、organization_id 落地镜像,完成后记录一次游标边界(拉一次 changes 取 newest_seq)。
  2. 轮询增量:固定周期带 since=<本地 cursor> 拉取,同一批循环到 has_more=false 才提交 cursor,周期取 30 至 60 秒。
  3. 定期全量校对:每日一次全量比对,差异一律以全量为准覆盖本地,兜住写入失败、事件缺失与父子关系变化。
  4. 幂等应用:upsert 按主键覆盖,delete 按主键软删除,保留历史数据外键。

6.4 已知限制

  • 组织的状态与移动事件信息量有限:状态事件只带 id 与 status,移动事件只带 id 与 parent_id,都不带 path,组织停用也不会为子孙逐个发事件。收到组织 status 或 parent_id 变更后应重新拉全量,禁止靠增量 payload 推导父子关系。
  • 默认全量会裁掉不可达子树:组织可见性判定是“自身与全部祖先都启用”,父组织停用后状态仍为 1 的子组织连同其人员不会出现在默认导出里。镜像一律带 include_disabled=true&include_disabled_users=true,带上之后整棵树按原层级输出,只用 status 区分停用与否,不会把停用节点提升到根。
  • data 键名不统一:source=hub 的部分事件用 id,source=wecom 用 organization_id,同一含义两个键名。
  • 事件来源只覆盖上表列出的写路径,其它写入(例如人员资料调整)不发事件,只能靠定期全量校对发现。
  • 变更流水有保留上限,内存实现固定保留最近 20000 条;MySQL 实现未见裁剪逻辑,保留期以实现为准。长期停止轮询的下游一律按“落后过多”处理,走全量重建。
  • 目录密钥只在服务端配置 HUB_DIRECTORY_KEYS,无管理界面、无在线轮换,轮换需改配置并重启;窗口期可逗号并列两个密钥。

7 企业微信

企业微信只对接 hub,下游不需要企业微信凭证,通过第 6 章目录接口消费结果,source 为 wecom 的变更即来自该链路。

7.1 配置项

GET、PUT /api/v1/auth/admin/wecom/config(需 admin 角色)。

字段 类型 默认 说明
enabled bool false 是否启用同步与定时任务;未启用时同步、记录、待认领接口返回 404 404001(企业微信同步未启用)
corp_id string 空 企业 ID,enabled=true 且为空时 400 400001(启用同步时必须填写企业微信 CorpID)
agent_id string 空 自建应用 AgentId,为空时响应省略该字段
secret string 只写 读取不返回明文,只有 secret_configured 与 secret_masked;保存时传空值表示保留原密钥
base_url string https://qyapi.weixin.qq.com 上游接口地址,专有云或代理场景才改
root_department_id int 1 同步根部门 ID,小于等于 0 归一为 1
sync_interval_seconds int 7200 定时周期秒数,小于等于 0 取 7200,小于 300 提升为 300
auto_create_users bool false 无法匹配到已有账号时是否自动建号
deactivate_missing bool false 上游不再出现的人员是否停用

保存返回 400 400001 且文案为“配置保存失败,请检查同步周期与根部门”即配置校验未通过。

7.2 立即同步与同步记录

POST /api/v1/auth/admin/wecom/sync 手工触发一次,data 为本次执行记录;未配置返回 400 400001(请先完成企业微信配置);企业微信接口报错返回 HTTP 502 + 500001。GET /api/v1/auth/admin/wecom/runs?limit= 查历史,limit 默认 20、上限 100,data 为 {items, total}。

记录字段 说明
run_id、trigger_type、status、started_at、finished_at、duration_ms trigger_type 取 manual、schedule;status 取 running、success、failed、skipped
departments_total / _created / _updated / _disabled、users_total / _created / _updated / _disabled 部门与人员的总数、新建、更新、停用计数
claims_created、message、operator 本轮新增待认领数、结果说明、操作人(定时任务为空)

7.3 同步语义

  • 人员对同步只停用、从不启用。上游不再出现的已绑定账号只在 deactivate_missing=true 时置为 status=0,不物理删除;管理员手工启用的账号若仍不在上游名单,下一轮同步会再次停用。
  • 组织与人员相反:重新出现在上游的部门会被自动置回启用;部门在 hub 侧被删除时,绑定关系会重建新的组织节点。
  • 停用组织有两套语义,取决于触发方。管理员在控制台的停用是显式意图,按 path 前缀级联停用整棵子树;同步来源的停用只作用于上游消失的那一个节点,显式不级联(ADR-0010),其子组织保持原状态,除非上游同样不再返回它们。同步为了顺序稳定按 path 长度由长到短逐个处理,这与级联无关。
  • 启用组织一律不级联,两条路径都只改本节点。因此管理员手工停用一棵子树后,若只有根部门重新回到上游,重新启用的也只是根节点,子部门仍需逐个手工启用或由上游逐层返回。
  • 停用组织不会停用人员账号,人员停用只由人员维度的判定产生。根组织(parent_id 为 0)不允许停用,存储层直接拒绝。
  • 组织编码固定为 wecom-<部门ID>,同级重名时名称追加 (部门ID) 重试一次;人员主组织取上游 main_department。
  • 自动建号的密码哈希写入占位值 !sync-managed-no-password!,不是合法哈希,因此同步账号无法密码登录,见 7.5。
  • 权威字段划分:hub 权威为 account 与 RBAC 角色,企业微信权威为 display_name、email、avatar_url、组织归属、在职状态。下游不要用企业微信字段覆盖 account。

7.4 待认领队列

无法自动落号的上游人员进入待认领队列,GET /api/v1/auth/admin/wecom/claims?status=pending|claimed|dismissed|all(非法值返回 400 400001),data 为 {items, total}。

reason 语义 处理
email_conflict 邮箱唯一命中已有账号,candidate_user_id 给出候选 用认领接口绑定候选账号
email_ambiguous 邮箱命中多个账号 先清理重复工号或邮箱,再绑定唯一账号
auto_create_disabled auto_create_users=false 且无法匹配 人工建号后绑定,或开启自动建号后重跑同步
account_conflict 建号时 account 重复 调整上游账号或停用本地重名账号后重跑

认领:POST /api/v1/auth/admin/wecom/claims/{id}/claim,请求体 {"user_id": 10086},目标账号必须存在且 status=1,否则分别返回 404 404001、400 400001(只能绑定状态为正常的账号);绑定成功后该用户的密码通道被关闭,账号 ID、角色与历史保留。忽略:POST /api/v1/auth/admin/wecom/claims/{id}/dismiss,data 为 {"dismissed": true}。记录已处理时返回 400 400001(该待认领记录已处理)。记录字段:claim_id、provider、external_id、external_name、email、account、reason、status、candidate_user_id、user_id、created_at、resolved_at、resolved_by,空值省略。

7.5 密码登录通道

同步账号默认不能密码登录:自动建号写占位哈希,认领绑定已有账号时清空密码哈希。管理员按人开启:PUT /api/v1/auth/admin/users/{id}/password-login,请求体 {"enabled": true, "expires_at": "2026-10-01T00:00:00Z"},enabled 必填,expires_at 省略时默认 7 天;响应 data 含 user_id、password_login_enabled、password_login_expires_at、source、generated_password,其中 generated_password 为 16 位随机密码、字符集排除易混字符、只回显一次。关闭通道同时清空该用户密码哈希。GET /api/v1/auth/admin/password-channels 只列出存在策略行的账号,字段为 user_id、account、display_name、password_login_enabled、password_login_expires_at、locked_until、source。不存在策略行的账号默认允许密码登录,同步账号是靠占位哈希挡住密码登录的。登录失败 5 次进入 10 分钟窗口统计,达到阈值锁定 15 分钟。

8 统一登录入口与登出边界

  • 登录入口只有 hub 一处(见 1.4):在 hub 登出即回到 hub 登录页,重新登录后重新落在统一门户,再点应用重新签发 ticket。已免登进入的下游会话不会被回收。
  • 当前版本不支持 back-channel 与 front-channel 单点登出,没有 end_session 端点,也不向下游推送登出通知。
  • POST /auth/logout(可选请求体 refresh_token)返回 204:吊销该用户全部刷新令牌并清除 hub 会话 Cookie。access token 是自包含 JWT,有效期内仍可被下游接受,默认有效期 15m,登出不即时生效。
  • 会话生命周期由下游掌控:下游用票据换取身份后建立本地会话,本地 TTL 应短于业务可接受的风险窗口,并自行实现空闲超时与主动登出。
  • 用户在 hub 被停用后,已建立的下游会话不会被回收,但下一次免登会被 user_inactive 拦住。需要即时下线的下游,自行轮询目录或调用令牌内省 POST /api/v1/auth/token/verify。
  • 标准 OIDC Provider 与统一登出属后续规划,当前版本未实现,排期以实现为准。

9 错误码与排错

code HTTP 含义
200 200 成功;票据校验的业务失败同样是 200,看 data.active
400001 400 请求参数无效、回调地址未登记、应用编码重复、状态值非法
401001 401 未登录、令牌无效、集成密钥无效或缺失、目录密钥不认识
403001 403 权限不足(缺 admin 角色)、应用已停用、用户未命中应用的任何授权角色、密钥与应用不匹配
404001 404 应用、用户、待认领记录不存在,或门户、企业微信同步未启用
500001 500 服务端内部错误;企业微信上游调用失败时为 HTTP 502 + 500001
现象 原因 处理
免登 404 404001 {code} 未注册(大小写不敏感) 核对 GET /api/v1/auth/admin/integrations
免登 403 403001 或门户看不到应用 应用 status=0 或 visible=0 管理员启用并设为可见
门户看不到应用(应用已启用) 应用未授权任何角色,或用户的角色不在 role_ids 里 在「应用接入 > 编辑 > 可访问角色」勾选用户所属角色,未授权的默认对所有人隐藏
免登 400 400001(回调地址未在应用中登记) redirect_uri 与白名单不完全相等 按协议、主机、端口、路径逐字符登记
票据校验 401 401001 密钥错误、应用被停用、旧密钥超 24 小时宽限期 重新下发或轮换密钥
票据校验 403 403001 app_code 与密钥不属于同一应用 用应用密钥时去掉 app_code
reason: ticket_invalid 票据重复使用,或值被截断、被 URL 解码改写 去掉重试;确认落地页未二次加载;取原值
reason: ticket_expired 落地到校验之间超过 ticket_ttl_seconds 精简跳转链路,必要时提高有效期(上限 300)
reason: ticket_audience_mismatch 用 A 应用密钥校验 B 应用票据 一个应用一套密钥,密钥与 code 固定配对
目录 400 400001 member_limit 超出 1-5000,或布尔参数非法 修正查询参数
since 小于 oldest_seq 流水裁剪或下游停机过久 全量重建后重新起算游标

10 对接自查清单

  • 已取得应用 code 与密钥明文,密钥存放在密钥管理服务或环境变量,不在代码仓库与前端产物中
  • launch_url 与全部 redirect_uris 已在 hub 登记,与浏览器实际访问地址逐字符一致
  • 免登落地页只接受 ticket 与 state,其它输入不参与鉴权
  • state 由下游服务端生成并校验,不一致直接拒绝
  • 票据校验只由后端发起并携带 X-Integration-Key,不经过浏览器、不写日志、不落库、不重试
  • 业务失败按 data.active 与 reason 分支处理,user_inactive 与 status != 1 一律拒绝并结束本地会话
  • 本地账号以 sub 为唯一映射键,不按 email 或 display_name 自动合并
  • 下游本地会话 TTL 与空闲超时自行控制,不依赖 hub 登出
  • 已撤掉下游本地登录、注册、找回密码入口,未登录访问 302 回 hub 站点首页,不再向用户索取下游账号密码
  • 票据缺失、过期或 active:false 时回到 hub,不回落到本地密码登录、不复用旧会话
  • 目录同步使用 X-Directory-Key,与应用密钥分开保管
  • 首次全量已记录游标,增量轮询循环到 has_more=false 才提交游标
  • 每日全量校对任务已上线,差异以全量为准
  • 组织 status、parent_id 类变更触发全量校对,不从增量 payload 推导父子关系
  • truncated=true 与 since < oldest_seq 都会触发全量重建
  • 生产链路全部 HTTPS,票据不经过第三方资源与埋点脚本
  • 已与 hub 运维确认密钥轮换联系人,24 小时双活窗口内完成切换