# Auth Center OIDC 用户受控 JIT 预配

## 适用边界

Gateway 只在 OIDC Token 已通过签名、Issuer、Audience、有效期、`tid`、Scope 和应用角色校验后执行 JIT。认证中心的稳定 `sub` 是外部用户标识；Gateway 不读取、不保存或公开 Keycloak 内部 ID，也不向 Token 增加 `gatewayUserId`。

本次保持单 Gateway 租户：管理员在统一认证 Draft 中把 Auth Center 的已验证 `tid` 显式绑定到一个已存在、启用且配置了启用中默认用户组的 Gateway 租户。Token 不能创建租户。

## 配置

OIDC、JIT 和浏览器会话不读取业务环境变量。管理员在 Auth Center 的通用“应用接入”向导选择 `OIDC 登录` 与 `API 验证`，生成一次性接入码；再到 Gateway“系统设置 → 统一认证”提交认证中心地址、接入码、Gateway API/Web 地址和本地租户映射。系统自动推导回调及退出地址，生成 Session 加密密钥并保存到部署级 SecretStore。

- JIT、Legacy JWT 兼容和 Session 时限属于 Revision 策略，可在 Draft 中修改；默认闲置 30 分钟、绝对 8 小时、提前 60 秒刷新。
- JIT 关闭时停止创建新用户，但已有 `source=oidc + external_user_id=sub` 映射仍会解析和同步登录时间。
- 本地租户不存在、公共 Client 不可用或 Discovery/Issuer/JWKS 校验失败时，Revision 不能激活，当前 Active Runtime 不受影响。

## Web Console 浏览器会话

- Web 只跳转 `GET /api/v1/auth/oidc/login`。Gateway 生成 state、nonce、PKCE verifier，并以 Authorization Code + PKCE S256 完成换码；公共 Client 请求只发送 `client_id`，不使用 Client Secret。
- Access Token、Refresh Token 和 ID Token 使用 AES-256-GCM 加密后存入 PostgreSQL；数据库只保存随机 Session Cookie 的 SHA-256。浏览器 JavaScript、响应体和 Web Storage 均不接触 Token。
- 浏览器只保存 32 字节随机、`HttpOnly + SameSite=Strict` 的 Session Cookie。新标签页通过该 Cookie 调用 `/api/v1/me` 恢复登录态；Gateway 不签发第二枚 JWT。
- Access Token 继续保持 5 分钟。认证请求发现剩余时间不超过 60 秒时使用 Refresh Token 自动刷新；多实例通过 PostgreSQL 刷新租约保证同一版本只刷新一次，并原子保存旋转后的 Refresh Token。
- Session 闲置 30 分钟、绝对最长 8 小时。闲置 5～30 分钟后的首个请求可自动刷新；超过闲置或绝对期限不会刷新，必须重新登录。浏览器不运行定时刷新。
- 所有 Web API 请求使用 `credentials: include`。Cookie 鉴权请求的 Origin 必须与当前健康 Active Revision 的 Gateway Web 地址精确匹配，否则返回结构化 403；不接受 `*`。
- Cookie 的 `Secure` 属性由 Revision 中的 Gateway API 公网地址推导：生产地址只允许 HTTPS；本地开发允许 localhost HTTP。可信 Origin 由 Gateway Web 地址精确推导，不接受 `*`。
- `POST /api/v1/auth/oidc/logout` 校验可信 Origin、删除本地 Session、使用公共 Client ID 撤销 Refresh Token，并跳转 Auth Center 退出地址；`DELETE /api/v1/auth/oidc/session` 保留为幂等的本地删除接口。
- 第一次接入、确认禁用或 Active Runtime 故障恢复时，跨 Origin 管理页面使用部署级精确 bootstrap CORS；生产部署建议由反向代理通过同源 `/gateway-api` 暴露 API。该配置不包含 Issuer、Client 或 Scope。
- Session Encryption Key 由 Gateway 服务端生成，只以 Secret 引用进入 Revision，不得复用 JWT Secret，也不会进入数据库、响应、日志或浏览器。禁用统一认证会清理现有 BFF Session；重新配对后用户需要重新登录。

## 数据和事务语义

- 查找键固定为 `source=oidc + external_user_id=sub`；`user_key` 由规范化 Issuer 和 `sub` 做 SHA-256 派生，不按邮箱、手机号、昵称匹配。
- 首次登录在一个事务中创建 `gateway_users` 投影、绑定租户默认用户组、初始化 `resource` 钱包并写入 `identity.oidc_user.provisioned` 审计事件。
- 重复或并发登录依赖现有唯一约束和冲突处理返回同一个本地用户，不重复创建钱包或首次预配审计。
- 后续登录只同步 Token 用户名、应用角色、`last_login_at`、`synced_at` 和 `source_updated_at`；不覆盖人工资料或用户组，不重新启用已禁用/删除账号。
- JIT 不生成 API Key 或任何 secret。用户仅在主动创建 API Key 或进入需要 Key 的工作流时触发生命周期操作。

## 对外错误

所有错误沿用 `ErrorEnvelope`：

| HTTP | code | 含义 |
| --- | --- | --- |
| 403 | `GATEWAY_USER_NOT_PROVISIONED` | JIT 关闭且没有已有本地映射 |
| 403 | `GATEWAY_USER_DISABLED` | 本地用户已禁用或删除 |
| 503 | `GATEWAY_TENANT_UNAVAILABLE` | 配置租户或用户组不存在/未启用 |
| 503 | `GATEWAY_USER_PROVISIONING_FAILED` | 事务或存储故障；响应不暴露内部错误 |
| 404 | `OIDC_BROWSER_SESSION_DISABLED` | Gateway 浏览器会话功能未启用 |
| 401 | `OIDC_SESSION_INVALID` | Session 不存在、Cookie 格式错误或 Token 身份不匹配 |
| 401 | `OIDC_SESSION_EXPIRED` | 闲置/绝对期限已到或 Refresh Token 已失效 |
| 503 | `OIDC_SESSION_REFRESH_UNAVAILABLE` | Access Token 已过期且认证中心暂时不可用 |
| 503 | `OIDC_SESSION_STORE_UNAVAILABLE` | 数据库或 Token 密文不可用 |
| 403 | `OIDC_SESSION_CSRF_REJECTED` | Cookie 写请求缺少可信 Origin |

`ErrLocalUserRequired` 仅作为防御性内部错误保留，对外统一转换为结构化 403。

## 验收与重新接入

自动化门禁通过后，依次验证本地真实 OIDC 和 `auth.51easyai.com` Staging 专用测试租户。证据应包含脱敏 Claims、网络截图、本地 Gateway 用户记录、Trace ID、Gateway/Auth Center 审计 ID及 200/401/403/503 负向证据；不得保存 Token、授权码、密码或 Secret。

Active Revision 可原位重新验证。需要改变远端身份资源时，先确认本地 Break-glass Manager，禁用当前配置，再使用 Auth Center 新接入码创建、验证和激活新 Revision；历史 `superseded` Revision 只用于审计，不能直接回滚或重新激活。已经创建的 `source=oidc` 测试投影保留为惰性数据，不自动删除、迁移或合并。