iam-service/docs/INTEGRATION_GUIDE.md

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

鉴权流程图（请求 → 认证 → 租户隔离 → 权限校验）

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 统一裁决。