feat(auth): 统一身份 - 增加可选IAM快捷登录并保留原业务权限

2026-09-10 10:33:03 +08:00
parent 27fbef9321
commit aa0d22bbe2
518 changed files with 5919 additions and 13 deletions
@@ -0,0 +1,53 @@
+# IAM 统一账号快捷登录
+
+在原账号密码、企业微信入口之外提供可关闭的 OIDC 登录方式。不开启配置时不访问 IAM、不创建事务文件，也不改变原登录行为。
+
+## 配置
+
+在服务器私密 `server/.env` 增加：
+
+```ini
+[IAM]
+ENABLED = false
+ISSUER = https://login.zhenyangtang.com.cn/auth/realms/iam-hub
+CLIENT_ID = zyt
+CLIENT_SECRET = CONFIGURE_PRIVATE_CLIENT_SECRET
+REDIRECT_URI = https://admin.zhenyangtang.com.cn/adminapi/iam/callback
+API_URL = https://login.zhenyangtang.com.cn/iam-api
+APPLICATION_ID = zyt
+APPLICATION_TOKEN = CONFIGURE_PRIVATE_APPLICATION_TOKEN
+PUBLIC_URL = https://admin.zhenyangtang.com.cn
+```
+
+Keycloak 的 `zyt` client 仅登记上述精确 HTTPS 回调，开启 Authorization Code 与 PKCE S256；不启用密码授权。配置完成后再设 `ENABLED=true`。
+
+## 账号和权限
+
+- IAM 必须存在有效员工、`zyt` 应用授权和经管理员确认的账号绑定。`externalAccountId` 是已存在的甄养堂管理员 ID，不是账号名称。
+- 不按用户名或邮箱自动合并，不自动生成 root、不改已有角色/部门/数据范围。
+- 本次新员工按用户指定的 **医助角色 ID 2** 开通，沿用原新增账号流程（含 IM 账号导入），再显式绑定到 IAM。后续人员也需由管理员明确开通与绑定；没有绑定时快捷登录拒绝，而非猜测账号。
+- 登录签发原 `AdminTokenService` token，继续遵守本地 disable、软删除、单点/多点登录、首次改密以及强制绑定企微规则。
+- 新账号默认 `is_paw=0`。完成首次改密、绑定企微之前不会跳过原有业务门禁。
+- 此版本在每次新快捷登录时检查 IAM 状态，不批量撤销既有业务会话，也不宣称已实现 IAM 停权事件实时踢下线。
+
+## 协议与部署
+
+端点为 `/adminapi/iam/config`、`start`、`callback`、`exchange`。浏览器保存独立 HttpOnly/Secure/SameSite=Lax 事务 Cookie；state、nonce、PKCE 与一次性兑换码绑定浏览器。URL 中不传业务 token，兑换只能 POST 且校验来源。事务文件保存在应用 runtime 的 `iam-login` 私有子目录，0600，受文件锁保护。当前单服务器 PHP-FPM 多进程共享该目录；扩展到多机前须换成共享原子存储。
+
+JWT 使用锁定的 firebase/php-jwt，校验 RS256、签名、issuer、audience/azp、有效期和 nonce；出站 TLS 校验保持开启，不跟随重定向。
+前端通过服务器开关显示按钮，兑换后复用现有 token 缓存与页面分流，IAM 失败时原账号及企微入口仍可使用。
+发布静态文件保留旧哈希资源，最后更新入口，避免已打开页面加载旧资源时报错。
+
+## 验证与回退
+
+```sh
+php server/tests/IamOidcClientTest.php
+php server/tests/IamLoginTransactionTest.php
+php server/tests/AdminDesktopAuthContractTest.php
+php server/tests/AdminDesktopSessionBehaviorTest.php
+php server/tests/AdminMultiRoleRegressionTest.php
+php server/tests/DataScopeMultiRoleTest.php
+NODE_PATH=admin/node_modules node server/tests/IamLoginUiContractTest.mjs
+```
+
+回退时先关闭 IAM 开关，再恢复本次代码和静态入口备份，不清空会话、用户、角色、业务数据库或全部缓存。新创建的员工与医助账号保留，由管理员决定是否停用。