DataOps-platform/docs/phase3/P3_WP02_ENTERPRISE_IDENTITY.md

P3-WP02 企业统一身份与 SSO 工程交付说明

1. 状态与边界

• 工程状态：ENGINEERING_COMPLETE_ENTERPRISE_IDP_UAT_BLOCKED
• 企业身份输入：identity = TBD_EXTERNAL
• 企业试点目标：pilot_goal = TBD_EXTERNAL
• 本工作包完成了协议、持久化、接口、浏览器和安全门禁的工程闭环，但没有目标企业 IdP、企业实名账号、批准的 Claims 矩阵和生命周期事件，不能声明企业联调或 UAT 通过。
• IAM-05～12、IAM-17 的最终功能台账成熟度仍由 P3-WP14 按真实证据统一收口。

2. 已实现能力

1. OIDC Authorization Code + PKCE S256，state、nonce、verifier、provider 版本和回调地址 一次性绑定；严格校验 JWKS、非对称算法、Issuer、Audience、有效期和重放。
2. IdP 配置追加版本，secret 仅接受 env:DATAOPS_OIDC_[A-Z0-9_]+ 专用命名空间引用； 管理接口仅返回掩码；支持 dry-run、激活、停用、轮换、 JWKS 连通性检查和精确回调/登录后跳转白名单。所有身份 URL 必须为公网 HTTPS，拒绝 localhost、私网/保留地址字面量、userinfo 和 fragment。OIDC 出站会解析并检查全部 DNS 地址，生产连接固定到已验证的公网 IP，同时以原 hostname 执行 TLS SNI、证书主机名校验和 Host 头校验，底层不再对 hostname 二次解析；禁止重定向，限制连接/读取超时和响应大小， 并严格校验 HTTP、Content-Type 与 JSON。
3. Claims 映射必须包含类型和长度合规的 subject、用户名、显示名、部门和非空字符串组数组； group rule 必须是严格 Schema 的字符串数组且至少映射一个批准角色；规则版本化、确定性输出 admin/editor/viewer、业务域、对象类型、环境和数据范围；无匹配规则默认拒绝。
4. 受控目录增量入口使用 source event id 与 cursor，重复载荷幂等、同 id 不同载荷失败； 身份键固定为 provider + subject，cursor sequence 单调推进并保留 checkpoint/冲突记录； JOINER/MOVER/LEAVER/DISABLE/RESTORE 触发 token version 递增和会话回收，恢复按当前映射 重算，不恢复历史高权角色。身份/角色变更、会话撤销、event 和 checkpoint 在同一数据库 事务提交，按 provider + source 串行，任一步失败均整体回滚。
5. DEPARTMENT/GROUP 组织节点支持 provider 隔离的 UPSERT、DISABLE、RESTORE、父节点和 扩展属性；复用同一 cursor、幂等、冲突和审计协议，不允许停用或恢复不存在的节点。
6. access token 在企业会话中增加 sid、token_version 和 identity_source，服务端验证会话； opaque refresh 只保存 SHA-256，旋转后旧 token 重放撤销整个 family，另有并发上限、 注销、指定撤销和风险终止。并发创建会话先锁定用户行，再计算和回收超限会话；IdP 激活或 轮换递增该 provider 的 token version 并撤销旧会话。active IdP 存在时拒绝所有无 sid 的 历史本地 token；身份状态查询失败时本地登录和 token 校验均失败关闭。
7. active IdP 存在时，普通本地登录默认关闭；应急账号须有请求、两个不同实名管理员审批、 最长两小时有效窗口和事后复核，请求人、应急账号不得自批；应急账号必须是未链接企业 身份的有效本地管理员，实际登录和刷新均再次校验该资格；refresh 后的到期时间不超过原 审批窗口；会话绑定请求与到期时间，关闭、到期和复核立即拒绝并撤销。
8. 配置、OIDC、映射、目录、refresh/logout、会话撤销、风险终止、应急申请和后续动作进入 统一身份审计；safe detail 递归移除 code、token、verifier、secret、cookie、password、 assertion 和完整 claims。
9. OIDC callback 将用户/link、角色、旧会话撤销、新会话和一次性交换码放在同一事务，任一 持久化失败整体回滚。管理 API 对必填字段、UUID、整数、日期和网络/JSON 错误返回受控 4xx/502，不回显底层异常；IdP 版本和审计仅 identity:manage 可读，会话仅 identity:operate 可读，列表不返回 subject、family、refresh 或应急绑定字段。
10. 登录页展示 active provider，回调页只交换一次性 code；access token 使用 sessionStorage， 自动清理历史 localStorage，401 最多进行一次共享 refresh，退出调用服务端撤销。

3. 生产配置约束

• 先依次执行前向迁移 20260802_470 与安全加固迁移 20260802_471，不得降级删除身份和 认证证据或放宽 secret ref 边界。
• 每个 secret ref 必须由受控运行环境注入；接口和审计只显示引用，不显示秘密。
• IDENTITY_COOKIE_SECURE 生产必须保持 true；反向代理必须保留 HTTPS Origin 和安全 Cookie。
• IdP 配置激活前必须完成 dry-run、JWKS 连通性检查和回调地址注册；生产不允许临时宽泛 callback，也不允许把 access/refresh token 放入 URL。

4. 企业 UAT 剩余门禁

以下证据未提供，状态保持阻断：目标 IdP 租户/Issuer/Client/证书；批准的 group/Claims 与 权限矩阵；入职、转岗、离职、冻结、恢复事件；两名实名应急审批人；企业安全负责人； 预生产域名、Origin、Cookie 和网络策略。UAT 必须验证正常登录、错误算法/Issuer/Audience、 角色和数据范围、转岗离职回收、refresh 重放、并发/风险撤销、IdP 故障应急及全链审计。