WebChat 多租户 spec ④：企业 SSO（OIDC 统一认证）

[hrygo]

Summary

Closes #756

标准 OIDC Authorization Code flow + PKCE，一个实现覆盖全部国内主流统一认证厂商（派拉/玉符/阿里云 IDaaS/腾讯云 IDaaS/宁盾/Authing/竹云/华为 OneAccess/TOPIAM）及国际 IdP（Keycloak/Okta/Azure AD/Google Workspace）。

核心组件

组件	文件	说明
OAuthProvider	internal/security/oauth_provider.go	OIDC 客户端（discovery + token exchange + ID Token 验证）
OAuthManager	internal/security/oauth_manager.go	多 provider 注册表（支持热重载）
OAuthHandlers	internal/gateway/oauth_handlers.go	login / callback / providers HTTP 端点
State cookie	internal/security/oauth_state.go	HMAC 签名，CSRF + PKCE + provider 校验
user_identities 表	migration 020	(provider, subject) → user_id 唯一映射
Config	internal/config/oauth_types.go	oauth.providers[] 配置 + 验证

安全设计

• Authorization Code flow + 强制 PKCE（S256） — 即使 code 被截获，无 verifier 也无法 exchange
• State CSRF 防护 — HMAC 签名 cookie（5min TTL），state 绑定 provider
• ID Token 验证 — JWKS 签名验证 + iss/aud/exp 校验（go-oidc 自动处理）
• Provider 注入防护 — name 只允许 [a-z0-9-]+ + 注册表精确匹配
• 不自动合并账号 — (provider, subject) 首次登录自动建号，email 不参与关联

与 spec ① 的关系

与密码登录并存，均为一等公民。顺带 wire spec ① 的 auth_handlers（routes.go 的 TODO(spec ⑥) 解除）——spec ④ 交付后 WebChat 后端认证体系完整。

配置示例

oauth:
  external_url: "https://hotplex.example.com"
  providers:
    - name: "keycloak"
      display_name: "企业 SSO"
      issuer: "https://sso.example.com/realms/main"
      client_id: "hotplex"
      client_secret: "${OAUTH_KEYCLOAK_SECRET}"

测试（24 test，make quality 全绿）

测试	数量	覆盖
store identity	4	CRUD + UNIQUE 约束 + not found
state cookie	7	set/verify/CSRF/expired/tampered/missing/mismatch
config	10	validate/scopes/claims/callbackURL/duplicate/invalid
mock IdP 端到端	3	discovery → authURL → PKCE exchange → ID Token 验证 → claims 提取

mock IdP 测试使用 httptest.Server 模拟完整 OIDC provider（discovery + JWKS + token endpoint），用 RSA RS256 签名真实 JWT，验证 go-oidc 完整验证链路。

依赖

• github.com/coreos/go-oidc/v3 v3.18.0（新增）
• golang.org/x/oauth2 v0.36.0（indirect → direct）

Checklist

• migration 020（SQLite + PG 双版本）
• user_identities 表 + store 方法（SQLite + PG）
• OAuthProvider OIDC 客户端
• OAuthManager 多 provider 管理
• State cookie 安全机制
• OAuthHandlers HTTP 端点
• Config 类型 + 验证
• routes.go wire（auth + oauth）
• gateway_run.go 初始化 OAuthManager
• 单元测试 + mock IdP 集成测试
• make quality 全绿