zyt/docs/iam-quick-login.md

IAM 统一账号快捷登录

在原账号密码、企业微信入口之外提供可关闭的 OIDC 登录方式。不开启配置时不访问 IAM、不创建事务文件，也不改变原登录行为。

配置

在服务器私密 server/.env 增加：

[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 失败时原账号及企微入口仍可使用。 发布静态文件保留旧哈希资源，最后更新入口，避免已打开页面加载旧资源时报错。

验证与回退

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 开关，再恢复本次代码和静态入口备份，不清空会话、用户、角色、业务数据库或全部缓存。新创建的员工与医助账号保留，由管理员决定是否停用。