接入 Hydra 授权、客户端管理与统一注销

docs/client-management.md

@@ -0,0 +1,56 @@
+# OAuth2/OIDC 客户端管理
+
+本服务通过受限 API 管理 Hydra 中的第一方 confidential authorization-code 客户端。
+API 没有管理 UI，沿用浏览器 Spring session；调用者必须完成有效的密码 + WebAuthn MFA，
+且直接属于配置的管理组。默认组列表为空，拒绝全部管理操作。
+
+```yaml
+iam:
+  clients:
+    admin-group-dns:
+      - CN=IAM Administrators,CN=Users,DC=example,DC=test
+```
+
+按完整 DN 匹配，保持与 AD 仓储一致的直接组语义，不展开嵌套组。可配置一个统一粗粒度
+管理组，不要求每个应用建立独立 admins 组。组成员来自本次目录登录快照，变更后需重新认证。
+
+| 方法与路径 | 行为 |
+| --- | --- |
+| GET `/api/iam/session` | 获取当前 session 的 CSRF headerName/token |
+| GET `/api/iam/clients?page=0&size=20` | 返回 Hydra 分页内支持的客户端，size 1–100 |
+| POST `/api/iam/clients` | 创建，201 返回 `{client, secret}`，密钥仅此次返回 |
+| GET `/api/iam/clients/{id}` | 查询，不返回密钥 |
+| PUT `/api/iam/clients/{id}` | 替换可管理字段，保留现有密钥 |
+| DELETE `/api/iam/clients/{id}` | 删除，204 |
+
+写操作必须携带当前 session cookie 与 GET session 返回的 CSRF 请求头。匿名返回 401，
+因素不足、缺少管理组或 CSRF 不符返回 403。CSRF 默认由 Spring Security 处理，没有绕过路径。
+成功变更记录 action、client ID 和操作者稳定目录标识，不记录密钥。没有 bearer 管理接口。
+
+POST/PUT 请求示例（PUT 的 id 必须等于路径）：
+
+```json
+{
+  "id": "example-app",
+  "name": "示例应用",
+  "redirectUris": ["https://app.example.test/oidc/callback"],
+  "scopes": ["openid", "profile", "email", "groups"],
+  "postLogoutRedirectUris": ["https://app.example.test/logged-out"],
+  "backchannelLogoutUri": "https://app.example.test/oidc/backchannel-logout",
+  "frontchannelLogoutUri": "",
+  "loginEnabled": true
+}
+```
+
+回调必须 HTTPS（隔离开发允许 loopback HTTP），不允许通配符、fragment 或 URL 用户信息。
+本轮固定 `authorization_code`、`code`、`client_secret_basic`、public subject；scope 限于上述
+四项且要求 openid。不接收任意 Hydra 字段、密钥、签名配置或授权类型，也没有通用 Admin API
+代理。不要为并不支持注销协议的应用登记虚构的端点。
+
+客户端与生成的 secret 由 Hydra 持久化；本服务不复制或缓存它们。管理员应在创建时安全保存
+secret。暂不提供密钥轮换接口。Hydra 版本固定，更新时省略 secret 以保留原值；集成测试验证
+创建、重启后读取、更新后原密钥仍能认证、删除。测试 PostgreSQL 完全独立于真实开发 MFA 库。
+
+列表按 Hydra 原始分页过滤不支持的授权类型，空页不表示之后必无客户端；本接口不是已有
+全部 Hydra 客户端类型的迁移工具。禁用写入 Hydra metadata，后续授权即时重读并拒绝，
+已签发 token 的生命周期另由 issuer 和应用控制。