91 lines
4.1 KiB
Markdown
91 lines
4.1 KiB
Markdown
# 安全评估与接口治理建议（IAM Service）
|
||
|
||
本文面向本仓库当前实现，给出“暴露面审查、风险识别、接口分级、敏感操作二次验证、隐藏策略”建议，并标注已落地的控制点。
|
||
|
||
## 1) 当前接口暴露面概览（按访问级别）
|
||
|
||
### 公开接口（Public）
|
||
|
||
特点：无需 Bearer Token；可被外部直接调用（应最小化）。
|
||
|
||
- `POST /tenants/register`：创建租户
|
||
- `POST /auth/register`：租户内注册用户（依赖 Header `X-Tenant-ID`）
|
||
- `POST /auth/login`：租户内登录（依赖 Header `X-Tenant-ID`）
|
||
- `GET /scalar`：OpenAPI/Scalar 文档
|
||
|
||
### 认证接口（Authenticated）
|
||
|
||
特点：要求 Bearer Token；应默认通过网关/WAF 暴露。
|
||
|
||
- `GET /tenants/me`、`PATCH /tenants/me`、`DELETE /tenants/me`
|
||
- `POST /tenants/me/status`
|
||
- `GET /me/permissions`
|
||
- `GET/PATCH/DELETE /users...`、`GET/PUT /users/{id}/roles`
|
||
- `GET/POST /roles`
|
||
|
||
### 内部/平台接口（Internal / Platform）
|
||
|
||
特点：平台权限（系统角色）才能访问，建议网关层做更严格限制（IP allowlist、mTLS、独立域名等）。
|
||
|
||
- `GET/PUT /platform/tenants/{tenant_id}/enabled-apps`
|
||
- `GET/POST /platform/apps`、`GET/PATCH/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|reject`
|
||
|
||
## 2) 风险识别（重点）
|
||
|
||
- **租户创建为公开接口**：可能被滥用批量创建租户，造成资源耗尽、审计噪声、后续越权风险面扩大。
|
||
- **注册为公开接口**：对任意租户 ID 可注册用户（虽然要求 `X-Tenant-ID`，但租户 ID 可被枚举/泄露）。
|
||
- **平台接口暴露风险**：即便有平台权限控制，一旦 token 泄露将影响全局（enabled_apps 与 apps 注册表）。
|
||
- **文档暴露**：`/scalar` 默认公开，可能暴露内部接口与参数细节。
|
||
|
||
## 3) 已落地控制点（本次实现）
|
||
|
||
- **敏感操作二次验证（可选开关）**
|
||
- 通过环境变量 `IAM_SENSITIVE_ACTION_TOKEN` 启用二次验证。
|
||
- 当启用时，下列操作必须额外携带 Header `X-Sensitive-Token: <token>`：
|
||
- `POST /tenants/register`
|
||
- `DELETE /platform/apps/{app_id}`
|
||
- 目的：降低“单一 Bearer Token 泄露”或“误调用”带来的破坏面。
|
||
|
||
- **平台权限细分**
|
||
- apps 生命周期管理引入平台权限码：`iam:app:read|write|approve|delete`
|
||
- enabled_apps 管理权限码：`iam:tenant:enabled_apps:read|write`
|
||
|
||
## 4) 建议的接口分级制度（治理）
|
||
|
||
建议把接口按“公开 / 认证 / 内部平台”分级，并在网关与代码侧同时落实：
|
||
|
||
- Public（公开）
|
||
- 强制：限流、验证码/人机校验（可选）、IP 风控、灰度开关、审计
|
||
- 建议：对 `tenants/register` 改为“邀请制/工单制”，或迁移到平台后台
|
||
|
||
- Authenticated（认证）
|
||
- 强制：最小权限、全链路审计、错误码统一、分页上限、输入校验
|
||
|
||
- Internal / Platform（内部）
|
||
- 强制：网关层隔离（独立域名/路由、mTLS 或 IP allowlist）、更严格限流、短 TTL token、专用账号
|
||
- 建议：默认不在公开文档展示（需要登录后才能看到或独立文档入口）
|
||
|
||
## 5) 接口隐藏策略建议（不改变业务语义）
|
||
|
||
- 网关层
|
||
- 路由隔离：`/platform/*` 走独立 upstream 或仅内网可达
|
||
- 访问控制：IP allowlist、mTLS、JWT audience/issuer 分离
|
||
- 速率限制：对平台接口与租户创建设置更低阈值
|
||
|
||
- 版本管理
|
||
- 对内部平台接口采用独立版本前缀：如 `/platform/v1/...`
|
||
- 对外接口保持稳定；内部接口可快速迭代
|
||
|
||
- 文档权限
|
||
- 将 `/scalar` 拆分为 public 与 internal 两份，或对 internal 文档加登录保护
|
||
|
||
## 6) 下一步改造建议（按风险优先级）
|
||
|
||
1. 将 `POST /tenants/register` 从公开接口迁移为平台接口（或邀请制），并引入更强风控。
|
||
2. 对 `POST /auth/register` 引入租户级注册策略（开关、邀请、允许域名白名单等）。
|
||
3. 对 `/platform/*` 接口在网关实现“物理隔离”（内网 + mTLS）而不仅是逻辑权限校验。
|
||
|