feat(iam): add guarded identity management and ERP launch source

This commit is contained in:
2026-10-29 17:34:55 +08:00
parent bcd42a5c39
commit dcb0db8275
26 changed files with 1827 additions and 5 deletions
+65
View File
@@ -0,0 +1,65 @@
# IAM v2 关联管理与 ZYT → ERP 快捷登录
## 默认状态与部署次序
所有新功能由 `iam.v2_enabled` 控制,默认 **false**。关闭时不写新表、不登记来源会话,原密码、企微、IAM 入站登录保持原路径。本文只描述源码;生产开关、迁移、真实浏览器及三端联调需另行验收。
1. 备份部署版本与配置,审查并执行 `server/database/migrations/20261029_iam_v2.sql`(按实际表前缀调整)。此迁移只加六张表及独立菜单/权限,不给现有角色自动授予权限,不改账号与角色。
2. 中央先部署 v2 绑定墓碑、幂等恢复、固定来源回查、版本检查、源/目标访问授权、密码设置协议与签名事件。旧 v1 token 不得获得新管理权限。
3. 向 IAM 注册 application `zyt` 的固定 HTTPS 回调;固定目标仅 `zmxy-erp`。OIDC client 追加精确 self-link 回调,禁用任意重定向。
4. 用一次性合成账号完成三端测试后再开启 v2。配置放服务器私密环境,不写仓库或日志。
```ini
[IAM]
V2_ENABLED = false
V2_TOKEN = <dedicated-application-v2-credential-at-least-32-chars>
V2_INTROSPECTION_TOKEN = <distinct-callback-credential-at-least-32-chars>
V2_EVENT_SECRET = <distinct-HMAC-event-key-at-least-32-chars>
ERP_URL = https://<ERP-origin>
PORTAL_URL = https://<IAM-portal-origin>
```
中央专用凭据 scopes:`identity:search,identity:create,binding:read,binding:manage,binding:self,password:setup,launch:issue`,ZYT 不授予 target 的 `launch:accept`。
`API_URL`、`PUBLIC_URL`、`ISSUER`、OIDC client 配置沿用原配置。`ERP_URL/PUBLIC_URL/PORTAL_URL` 是固定 origin,不接受浏览器 URL。新功能的 v2 凭据与原 `APPLICATION_TOKEN` 分离。
## 固定端点
源应用所有路径前缀 `/adminapi/iam/v2`:
- `POST /proofs/introspect`、`POST /sessions/check`:专用 Bearer callback credential,不接受业务 token 代替。回包为中央约定的原生 JSON,不包业务 envelope。
- `POST /events/revocation`:`X-IAM-Signature=sha256=<HMAC-SHA256(raw-body)>`,`X-IAM-Event-ID` 必须等于 `body.id`;RFC3339 occurredAt、未来最多 60 秒、5 分钟重放窗口,持久化 event ID + digest 幂等;旧 bindingVersion 不撤销较新关联。
- `POST /launch/start`:同源、当前业务 token + 独立 HttpOnly source SID;只返回目标 `/iam/launch?source=zyt&intent=...`,在新标签页打开。
- `GET /launch/continue?transaction_id=...&intent=...`:IAM 注册的固定来源 continuation;目标 prepare 必须原样附加 opaque intent。比对源 HttpOnly intent cookie、源 SID、源 sessionVersion、固定两应用 ID 后,隐藏表单 POST 到 **`ERP_URL/api/erp/iam/v2/launch/callback`**。grant 和业务 token 均不进 URL。
- `POST /self-link/start` → `GET /self-link/callback`:当前本地近期认证 + OIDC code/PKCE/nonce 证明 IAM 同一用户;后端提交已验证 ID token,中央独立验证。前端没有指定个人 employee ID 的能力。
- `POST /password-setup` → `GET /password-continue?request_id=...&state=...`:只对本人已验证且待设置密码的 IAM 账号;中央初始返回 url/expiry/requestId,源 cookie + SID 绑定请求;continuation 隐藏表单 POST 到固定 `PORTAL_URL/portal/password-setup/authorize`。实际密码只在 IAM 页面输入。
用户 API 使用原业务 `{code,data,msg}` envelope。管理:accounts/identities/operations/audit/batch/jobs。每次 mutation 使用前端稳定 `Idempotency-Key`,自动 HTTP retry 关闭;中央按同一业务 payload 和 key 恢复已执行结果(proof 可刷新,不重复副作用)。operation/job 查询限定创建操作者及当前目标数据范围。
## 账号、会话与权限
- 新建来源会话保存独立浏览器 SID、原数据库 session ID、业务 token 的 SHA-256、账号凭据版本指纹、不可被续期更新的认证方法/时间、撤销版本。数据库会话轮换/到期、账号停用/删除、密码/企微关联/管理员标记改变立即使来源证明失效。
- 密码登录登记前再次真正核对密码 hash,不接受开发免密开关。企微入口的 TLS 必须校验后才登记 `wecom`。旧会话首次通过密码验证,或用原企微入口重新登录后登记;普通未关联业务使用不受影响。OIDC 使用原始 `auth_time`,缺失时不算近期认证。
- 每次管理写要求 5 分钟内认证、独立动作权限、现有 DataScope。权限:`iamV2/read|bind|create|unbind|rebind|batch`;不存在“未登记路由默认许可”的依赖。
- root、管理员/系统管理员/超级管理员角色或持有 IAM 管理写权限的目标视为敏感账号;没有双侧近期管理员证明则明确返回 `PROTECTED_ACCOUNT_REVIEW_REQUIRED`。批量预检将其列为 review,不发送中央,不静默跳过核验。
- 中央身份和授权是真源;本地绑定表是最长 30 秒快照。已关联账号的活跃业务请求在快照超时后回查;失权、版本变更、签名事件撤销来源 SID 和业务会话。服务不可用时相关受保护请求失败关闭。不宣称空闲客户端会在 30 秒内主动收到推送。
- 解绑/换绑保留本地业务账号和历史记录。`iam_local_identity` 是开户幂等账本,不是历史绑定全量镜像,永不删除。v2 撤销墓碑拦截旧账本自动重绑;中央旧版 v1 必须同样维护墓碑。较旧或相同版本的 verified 状态不能覆盖本地 revoked。
- 管理列表来自所有可见本地账号并回查中央,首次展示历史绑定;按状态筛选基于已对账快照,未读取过的历史行应先在“全部”中分页核验。姓名/手机号不是自动合并依据。批量用明确 local ID/employee ID 映射预检。
## 本地验证
```sh
php server/tests/IamV2SourceTest.php
php server/tests/IamV2RouteContractTest.php
NODE_PATH=admin/node_modules node server/tests/IamV2UiTest.mjs
php server/tests/IamLoginTransactionTest.php
php server/tests/IamProvisioningTest.php
php server/tests/IamOidcClientTest.php
NODE_PATH=admin/node_modules node server/tests/IamLoginUiContractTest.mjs
```
SQLite 合成测试不加载生产 `.env`、不发网络、不修改真实用户、角色或授权。UI 测试编译三个组件并执行新标签页处理逻辑,不能替代三端真实浏览器(Cookie/SameSite/新标签页)验收。原前端全量 typecheck 存量 60 条诊断,需按基线比较,不能批量掩盖。
## 回退
先将 `V2_ENABLED=false`,恢复上一已验证代码/静态构建。保留六张新表、旧开户账本、事件与审计记录、所有真实账号和业务数据。关闭 v2 停止委托登录/新证明,不撤回中央已执行的人事操作;错误关联通过有审计的显式解绑/换绑恢复,而非删表或恢复旧数据库。