CleanBot Hub

Appearance

用户认证与权限管理方案

**5.26 Update ** jiaxu provides the basic requirements for role/permission management in AM module. finalized by Web 5.28.

The suggested deadline of the first phrase is on June 6th.

By June 6th, we will accomplish AM module including the all 5 parts. the AM module will be integrated into demo env, User authentication will be manamaged by Cognito, AM module will provide role-based authorization for Services. The role-based authorization will meet the basic requirements finalized by Web 5.28.

一、系统架构概览 ​

                         +-----------------------------+
                         |     Frontend SPA / App      |
                         +-----------------------------+
                                      |
                     [1] Redirect to Cognito Hosted UI
                                      |
                         +-----------------------------+
                         |      AWS Cognito (User Pool)|
                         +-----------------------------+
                                      |
                       [2] Auth Code Callback to Frontend
                                      |
          [3] Frontend POST /auth/callback with code to Backend Auth API
                                      |
                         +-----------------------------+
                         |  Auth Gateway (Token 服务)  |
                         | - 换 token (access/refresh) |
                         | - Refresh token 写 HttpOnly |
                         | - 返回 access_token         |
                         +-----------------------------+
                                      |
            [4] All API Requests with access_token + HttpOnly cookie
                                      ↓
                         +-----------------------------+
                         |  AWS HTTP API Gateway       |
                         |  + JWT Authorizer (Cognito) |
                         +-------------+---------------+
                                       |
                          [5] Authenticated Forwarding
                                       |
+----------------+     +----------------+     +-----------------+
|  ECS 服务 A     |     |   ECS 服务 B    |     |  ECS 服务 C      |
| (e.g. 订单服务) |     | (e.g. 资产服务) |     | (e.g. 设备服务)   |
+--------+-------+     +--------+-------+     +---------+-------+
         |                      |                       |
 [6] 统一调用 SDK 本地缓存权限（Redis or in-mem）         |
         |                      |                       |
         |----------+-----------+-----------+-----------|
                                |
                        +-------------------+
                        |   AM 权限管理服务  |
                        |  - 权限模型校验    |
                        |  - 多租户支持      |
                        |  - API 权限判定    |
                        +-------------------+
┘

▶ 所有请求携带 access_token 调用 API Gateway (HTTP)

▶ API Gateway 使用 JWT Authorizer 验证 access_token 是否有效

▶ 请求转发至后端服务（ECS容器内）

▶ 后端服务通过调用 AM 服务：（目前的结构相当于api 权限管理后置，即在转发到api 前不去校验权限。到api后，在服务层面先调用AM服务校验权限。 这点有没有疑虑？大家需要讨论一下）
   - 校验租户归属
   - 校验资源权限
   - 获取用户角色/资源等上下文

▶ Token 过期返回 401，前端调用 /auth/refresh-token 自动更新 access_token

二、用户登录与 Token 管理（已经实现） ​

2.1 登录流程 ​

步骤说明
1. 用户访问系统，点击“登录”重定向至 Cognito Hosted UI 登录页
2. 登录成功后 Cognito 跳转回前端/callback?code=xyz
3. 前端将 code 发给后端 /auth/callback
4. 后端使用 AWS SDK 调用 Cognito 交换 token获取 access_token, refresh_token, id_token
5. access_token 返回前端，refresh_token 写入 HttpOnly Secure Cookie设置 Set-Cookie: refresh_token=xxx; HttpOnly; Secure

2.2 Token 自动刷新机制（前端发起）（zhangchaoyong 5月30 前在3D 模块部署上线，会输出文档和sanple供参考，其他页面分别实现即可。） ​

触发说明
前端访问接口返回 401表示 access_token 过期
调用 /auth/refresh-token后端读取 HttpOnly Cookie 中的 refresh_token，向 Cognito 刷新
新的 access_token 返回前端并重试原始请求
刷新失败（refresh_token 也过期）返回 401，前端重定向登录页重新登录

三、API Gateway 与后端权限校验流程（ruanhao 已实现） ​

3.1 JWT Authorizer（在 API Gateway 层） ​

验证项说明
access_token 是否存在Bearer token
token 是否过期解析并校验
是否是 Cognito 签发的使用 JWK 公钥签名验证
Claims 解析sub、email、cognito:groups 等

注意：JWT Authorizer 只做轻量认证，不做租户/权限判断。

3.2 后端服务鉴权机制（ruanhao 开发中， 等待jiaxu and ruobing 确认第一期am 业务要求，提供User cases，预计6月6日前完成第一期） ​

步骤说明
1. 后端服务收到 API 请求从 JWT Claims 中提取 sub, tenant_id, roles
2. 调用 AM 服务校验权限POST /am/verify-access
3. AM 服务验证租户绑定、角色权限、资源级访问控制
4. 返回权限校验结果与用户上下文信息例如可访问的楼层、模块、操作类型等
5. 业务服务决定是否执行请求逻辑

AM 模块在目前的场景下会成为访问热点，容易成为性能瓶颈。我们要考虑优化一下。 这里是否用缓存？ 还是就依赖DynamoDB？这个DB相对高效。@weidong @ahao 使用 Redis 缓存共享权限数据**（ruanhao 开发中）** [Service A] [Service B] [Service C] | | | +------> [Redis 权限缓存中心] <------+ | [AM 权限服务]

四、统一权限管理模块 AM 服务（ruanhao 开发中， 等待jiaxu and ruobing 确认第一期am 业务要求，提供User cases，预计6月6日前完成第一期） ​

功能模块：

模块说明
用户-租户绑定判断用户是否属于请求租户
角色管理用户拥有的系统角色列表
资源权限管理判断用户是否有权访问具体 API 或页面资源
API 鉴权为后端服务提供 /verify-access、/get-permissions 等接口

接口设计示例：

http
POST /am/verify-access
Authorization: Bearer <access_token>
{
  "tenantId": "abc",
  "resource": "/api/device",
  "action": "GET"
}

返回：

json
{
  "authorized": true,
  "userContext": {
    "userId": "xxx",
    "roles": ["admin"],
    "floorAccess": [1,2,3],
    "organization": "tenant-abc"
  }
}

五、跨服务统一鉴权流程（多个微服务模块）（ruanhao 开发中， 等待jiaxu and ruobing 确认第一期am 业务要求，提供User cases，预计6月6日前完成第一期） ​

所有后端服务统一走以下流程：

  1. 接收来自 API Gateway 转发的请求
  2. 提取 access_token

读取用户 ID + tenant_id，从 Redis 中拉取权限；

Redis 没有 → 请求 AM → 写入 Redis；

设置 Redis TTL，例如 10~15 分钟。

  1. 权限更新通知 管理后台更改权限后，AM 服务可通过：

Redis Pub/Sub

Kafka/MQ

Webhook/batch 清理 通知相关服务清除指定用户的权限缓存。

  1. 使用上下文做资源范围限制（如可访问楼层、组织）

优点：

  • 每个服务无需自行管理权限逻辑
  • 无需重复 JWT 解码校验
  • 可统一灰度发布、管理权限更新

六、Token 管理与续期责任划分 ​

模块责任
Cognito签发 access_token、refresh_token
前端存储 access_token，遇到 401 调用 /auth/refresh-token
后端 /auth 模块使用 HttpOnly Cookie 中的 refresh_token，刷新 access_token
AM 服务统一管理租户、角色、资源权限
API Gateway使用 JWT Authorizer 验证 access_token 是否有效
业务服务调用 AM 服务确认权限，避免自行处理 JWT

方案优势 ​

特点优点
Cognito + JWT标准认证机制，支持社交登录与 SSO
前端自动续期 + 后端 Cookie 存储 refresh_token安全 + 用户体验好
权限集中由 AM 服务控制易扩展、统一管理、多模块共享
JWT Authorizer 分离轻认证减轻后端压力
后端业务服务只需关注业务逻辑解耦权限与认证逻辑