126 lines
4.5 KiB
Markdown
126 lines
4.5 KiB
Markdown
# IAM Service 集成基线（接口清单 & 鉴权流程）
|
||
|
||
本文用于后续其他服务（如 CMS）集成时对齐以下能力基线：
|
||
|
||
- 租户隔离（Tenant Context / X-Tenant-ID / Token tenant_id 一致性校验）
|
||
- 用户注册/登录/刷新
|
||
- 基础租户管理
|
||
- 基于 JWT 的认证中间件
|
||
- RBAC 权限校验（服务端校验接口）
|
||
|
||
## 核心 Header/Token 约定
|
||
|
||
- `Authorization: Bearer <access_token>`
|
||
- `X-Tenant-ID: <tenant_uuid>`
|
||
- 当请求携带 `Authorization` 时，若同时提供 `X-Tenant-ID`，必须与 JWT claims 内的 `tenant_id` 一致，否则返回 403（`tenant:mismatch`）。
|
||
|
||
## 接口清单（REST）
|
||
|
||
### 文档
|
||
|
||
- `GET /scalar`：Scalar UI
|
||
- SSO 授权码接入：`docs/SSO_INTEGRATION.md`
|
||
|
||
### Auth（公开）
|
||
|
||
- `POST /tenants/register`：创建租户（初始租户管理员账号由后续 `/auth/register` + 首用户 bootstrap 完成）
|
||
- `POST /auth/register`：用户注册（需要 `X-Tenant-ID`）
|
||
- `POST /auth/login`：用户登录（需要 `X-Tenant-ID`）
|
||
- `POST /auth/login-code`：用户名密码签发一次性授权码（SSO，需要 `X-Tenant-ID`，并校验 redirectUri allowlist）
|
||
- `POST /auth/refresh`：刷新 access token（refresh token 一次性轮换）
|
||
- `POST /auth/code2token`：授权码换取 token（SSO）
|
||
|
||
### Auth（需认证）
|
||
|
||
- `POST /auth/logout`：退出登录（吊销 refresh token）
|
||
|
||
### Tenant（需认证 + 权限）
|
||
|
||
- `GET /tenants/me`（`tenant:read`）
|
||
- `PATCH /tenants/me`（`tenant:write`）
|
||
- `DELETE /tenants/me`（`tenant:write`）
|
||
- `POST /tenants/me/status`（`tenant:write`）
|
||
|
||
### Me（需认证）
|
||
|
||
- `GET /me/permissions`：查询当前用户在当前租户下的权限码列表
|
||
|
||
### RBAC（供其他服务复用）
|
||
|
||
- `POST /authorize/check`：服务端校验“当前用户”是否具备指定权限码（用于各业务微服务鉴权复用）
|
||
|
||
### User（需认证 + 权限）
|
||
|
||
- `GET /users`
|
||
- `GET /users/{id}`
|
||
- `PATCH /users/{id}`
|
||
- `DELETE /users/{id}`
|
||
- `POST /users/me/password/reset`
|
||
- `POST /users/{id}/password/reset`
|
||
- `GET /users/{id}/roles`
|
||
- `PUT /users/{id}/roles`
|
||
|
||
### Role（需认证 + 权限）
|
||
|
||
- `GET /roles`
|
||
- `POST /roles`
|
||
- `GET /roles/{id}`
|
||
- `PATCH /roles/{id}`
|
||
- `DELETE /roles/{id}`
|
||
- `POST /roles/{id}/permissions/grant`
|
||
- `POST /roles/{id}/permissions/revoke`
|
||
- `POST /roles/{id}/users/grant`
|
||
- `POST /roles/{id}/users/revoke`
|
||
|
||
### Permission（需认证 + 权限）
|
||
|
||
- `GET /permissions`
|
||
|
||
### Platform（需认证；平台权限）
|
||
|
||
- `GET /platform/tenants/{tenant_id}/enabled-apps`
|
||
- `PUT /platform/tenants/{tenant_id}/enabled-apps`
|
||
- `GET /platform/clients`
|
||
- `POST /platform/clients`
|
||
- `PUT /platform/clients/{client_id}/redirect-uris`
|
||
- `POST /platform/clients/{client_id}/rotate-secret`
|
||
- `GET /platform/apps`
|
||
- `POST /platform/apps`
|
||
- `GET /platform/apps/{app_id}`
|
||
- `PATCH /platform/apps/{app_id}`
|
||
- `DELETE /platform/apps/{app_id}`
|
||
- `POST /platform/apps/{app_id}/status-change-requests`
|
||
- `GET /platform/app-status-change-requests`
|
||
- `POST /platform/app-status-change-requests/{request_id}/approve`
|
||
- `POST /platform/app-status-change-requests/{request_id}/reject`
|
||
|
||
## 鉴权流程图（请求 → 认证 → 租户隔离 → 权限校验）
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[HTTP 请求进入] --> B[trace_http_request: 创建 http.request span]
|
||
B --> C{是否公开路径?}
|
||
C -- 是 --> H[进入 Handler]
|
||
C -- 否 --> D[JWT 认证中间件: Authorization Bearer]
|
||
D -->|验签/解析失败| E[返回 401]
|
||
D -->|成功| F[注入 AuthContext<br/>tenant_id/user_id/roles/permissions<br/>并 record span 字段]
|
||
F --> G[租户解析中间件: resolve_tenant]
|
||
G -->|缺少 X-Tenant-ID 且 Token 无 tenant| I[返回 400]
|
||
G -->|X-Tenant-ID 与 Token tenant 不一致| J[返回 403 tenant:mismatch]
|
||
G -->|成功| K[注入 TenantId 到 extensions 并 record span tenant_id]
|
||
K --> H
|
||
H --> L{是否需要 RBAC 权限?}
|
||
L -- 否 --> M[返回业务响应]
|
||
L -- 是 --> N[调用 AuthorizationService::require_permission]
|
||
N -->|无权限| O[返回 403 PermissionDenied]
|
||
N -->|通过| M
|
||
```
|
||
|
||
## 集成建议（面向业务微服务）
|
||
|
||
- 业务服务应直接复用 iam-service 的 JWT 认证中间件与 Tenant 解析中间件，并在业务路由层按以下顺序挂载：
|
||
- `trace_http_request`（生成请求 span）
|
||
- `authenticate`（解析 token 并注入 user/tenant 字段到 span）
|
||
- `resolve_tenant`（统一 TenantId 注入，并校验 X-Tenant-ID 与 token tenant 一致性）
|
||
- 权限校验禁止在业务侧实现一套 RBAC 聚合逻辑；应通过 `POST /authorize/check` 由 IAM 统一裁决。
|