36 KiB
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 登录页仍保留「注册」标签,但提交后由后端以403registration_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 转小写后查找;不存在返回404404001,已停用返回403403001(应用已停用)。 - 免登入口独立鉴权,与门户列表同一判定:用户没有命中该应用的任何一个授权角色时返回
403403001(无权访问该应用),绕过门户直接调用同样拿不到票据。 - 请求体两个字段都可省略。传
redirect_uri时必须与redirect_uris某一项完全相等,否则400400001(回调地址未在应用中登记);不传时落地地址为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 推荐同步流程
- 首次全量:
GET /api/v1/auth/directory?include_disabled=true&include_disabled_users=true,按user_id、organization_id落地镜像,完成后记录一次游标边界(拉一次changes取newest_seq)。 - 轮询增量:固定周期带
since=<本地 cursor>拉取,同一批循环到has_more=false才提交 cursor,周期取 30 至 60 秒。 - 定期全量校对:每日一次全量比对,差异一律以全量为准覆盖本地,兜住写入失败、事件缺失与父子关系变化。
- 幂等应用:
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 小时双活窗口内完成切换