6.7 KiB
IAM v2 关联管理与 ZYT → ERP 快捷登录
默认状态与部署次序
所有新功能由 iam.v2_enabled 控制,默认 false。关闭时不写新表、不登记来源会话,原密码、企微、IAM 入站登录保持原路径。本文只描述源码;生产开关、迁移、真实浏览器及三端联调需另行验收。
- 备份部署版本与配置,审查并执行
server/database/migrations/20261029_iam_v2.sql(按实际表前缀调整)。此迁移只加六张表及独立菜单/权限,不给现有角色自动授予权限,不改账号与角色。 - 中央先部署 v2 绑定墓碑、幂等恢复、固定来源回查、版本检查、源/目标访问授权、密码设置协议与签名事件。旧 v1 token 不得获得新管理权限。
- 向 IAM 注册 application
zyt的固定 HTTPS 回调;固定目标仅zmxy-erp。OIDC client 追加精确 self-link 回调,禁用任意重定向。 - 用一次性合成账号完成三端测试后再开启 v2。配置放服务器私密环境,不写仓库或日志。
[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 映射预检。
本地验证
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 停止委托登录/新证明,不撤回中央已执行的人事操作;错误关联通过有审计的显式解绑/换绑恢复,而非删表或恢复旧数据库。