zyt/docs/iam-hub-admin-integration.md

IAM Hub 员工统一登录接入

甄养堂管理后台使用 IAM Hub 作为员工身份、登录会话和统一停权来源；甄养堂原有角色、菜单、部门、岗位和业务数据权限继续保留在本项目中。

接入流程

1. 登录页调用 /adminapi/login/iamConfig 判断统一登录是否启用。
2. 员工点击“公司员工统一登录”，浏览器进入 /adminapi/login/iamStart。
3. 服务端生成一次性 state、nonce 和 PKCE verifier，并跳转 Keycloak。
4. /adminapi/login/iamCallback 交换授权码，校验 JWT 签名、Issuer、Audience、有效期、nonce 和 at_hash。
5. 服务端使用应用凭证查询 IAM Hub 开户上下文；已有管理员按绑定ID复用，新员工延迟创建本地管理员。
6. 本地管理员ID以服务端验证方式回写 IAM Hub，历史角色、部门、岗位和业务数据不迁移。
7. 本地登录令牌通过60秒一次性交换码放在 URL fragment 中，前端消费后立即清理地址栏。
8. IAM Hub 调用 /adminapi/iam/revocation，甄养堂验证原始请求体HMAC，禁用管理员、撤销全部会话并记录幂等审计。

数据库和配置

先执行：

server/sql/1.9.20260908/add_iam_hub_admin_identity.sql

再参考 server/.env.iam-hub.example 配置应用凭证、OIDC客户端和停权密钥。DEFAULT_ROLE_IDS 只用于首次创建的新管理员；已有账号绑定后继续使用原角色。

生产回调地址和 Keycloak 客户端必须一致。应用凭证与OIDC密钥只写部署环境，不提交仓库。