系统架构设计说明书 (SAD)

项目名称： sup-iam 身份识别与访问管理系统

编写人： 沈冬法

日期： 2025年12月15日

版本号： V1.0

1.引言

1.1编写目的

基于《sup-iam SAD》说明系统的总体架构设计，明确系统模块划分，职责边界与交互方式，为后序开发和运维提供参考

1.2 参考文献

《软件需求规格说明书.md》

2.架构设计目标与原则

2.1架构设计目标

  • 高内聚、低耦合
  • 支持高并发
  • 支持高可用
  • 明确的信任边界
  • 支持后续演进

2.2架构设计原则

  • 控制面与数据面分离
  • 无状态鉴权
  • 最小权限原则
  • 默认拒绝原则

3.系统总体架构

3.1 系统概念架构视图

描述 IAM 系统在整体安全架构中的角色划分，
包括 Client、Resource Server、Auth Server 与 IAM 管理系统之间的职责与信任边界。

其中Client和Resource Server为非项目组件

3.2 系统部署视图

描述 sup-iam 项目内部的实际组件拆分、部署关系与数据流，
不包含业务侧 Resource Server 的具体实现。
iam-api-server

  • 角色：控制面核心服务
  • 职责：
    • 管理User/Secret/Policy元数据
    • 为Auth Server和其它调用者提供策略与密钥查询能力
  • 不承担：
    • 在线鉴权决策
    • 实际业务流量入口
      iam-auth-server
  • 角色： 数据面鉴权决策服务
  • 职责：
    • 校验请求签名
    • 加载并评估授权策略
    • 返回可解释的鉴权决策
  • 不承担
    • 对元数据的直接管理
  • 设计约束
    • 无状态
    • 不保存用户登录状态

sup-iam-sdk-go

  • 角色：客户端集成层
  • 开发阶段: 项目主体阶段性完善后封装并提供的额外服务
  • 职责：
    • 封装签名，鉴权请求，API调用的细节
    • 降低接入IAM的成本
  • 接入方式：go包的方式接入，参数通过环境变量传参

redis

  • 角色：数据库缓冲与持久化层
  • 职责：
    • 缓存对元数据的查询结果
    • 缓存Auth Server产生的授权日志
  • 设计约束：
    • 应部署在可信网络中

MySQL

  • 角色：数据持久化层
  • 职责：
    • 持久化存储元数据
    • 自动化管理元数据
    • 提供高效的查询功能

iam-watcher

  • 角色：数据库监控层
  • 职责：
    • 定期处理过期数据
  • 设计约束:
    • 不能过度影响数据库效率

MongoDB

  • 角色：日志数据持久化层
  • 职责：持久化存储和管理日志数据

iam-pump

  • 角色：日志存储中间层
  • 职责：负责把日志从Redis转存到MongoDB中

iam-operating-system

  • 角色：运维组件
  • 职责：
    • 管理日志
    • 管理整个系统的全局参数
  • 开发阶段：属于项目主体完成后额外提供的运维组件

iam-webconsole

  • 角色：系统前端层
  • 职责：
    • 提供可视化的IAM管理功能
    • 降低管理的理解门槛
  • 开发阶段：属于项目主体完成后额外提供的前端组件
  • 部署网络环境：可信任的内网

iam-ctl

  • 角色： 系统软件层
  • 职责： 将SDK或者API调用封装成命令行工具
  • 开发阶段：属于项目主体完成后额外提供的命令行软件
  • 部署网络环境：可信任的内网

LoadBalance

  • 角色：负载均衡层
  • 职责：
    • 实现整体系统的横向扩展，高可用，负载均衡等
  • 部署：与IAM项目一同部署，或者购买第三方服务

架构图如下

3.2 系统部署流量视图

在 sup-iam 架构中，系统交互被划分为三类流量：

  • 控制流（Control Plane）

    • 指用户或运维人员通过 Web / CLI / API 对 User、Secret、Policy 等元数据进行管理的请求。

  • 鉴权流（Authorization Flow / Data Plane）

    • 指业务请求在访问受保护资源时，由 Resource Server 发起的实时鉴权请求。

  • 数据访问路径

    • 指 IAM 内部组件在处理控制流或鉴权流过程中，对 MySQL、Redis、MongoDB 等存储系统的访问关系。

3.2.1 控制面流量

1
2
3
4
[Auth Server]->[IAM系统]->[数据库]->[返回结果]
					^
					|
				[Client]

3.2.2 鉴权流量

1
[Client]->[Auth Server]->[IAM系统]->[返回结果]->[Resource Server]

3.2.3数据访问路径

4.核心服务架构设计

4.1 IAM管理服务架构

4.1.1 IAM组件

  • 组件名称:iam-api-server
  • 子模块划分
    • User管理模块
    • Secret管理模块
    • Policy管理模块
  • 职责边界
    • 不负责鉴权

4.1.2 Auth Server组件

  • 组件名称: iam-auth-server
  • 子模块划分
    • 请求校验模块
    • Secret加载模块
    • Policy加载模块
    • 策略评估模块
    • 决策输出模块

5. 鉴权处理流程

5.1 鉴权处理时序图

1
Client--发起带签名的访问请求-->Resource Server---发起鉴权请求->Auth Server

5.2 请求声明周期说明

  1. 请求访问
  2. 身份校验
  3. 权限评估
  4. 决策返回

6.数据架构与存储设计

6.1 MySQL存储

存储内容

  1. 存储User数据
  2. 存储Secret数据
  3. 存储Policy数据
  4. 存储审计Policy数据
    约束
  5. User的密码字段使用不可逆哈希加密

6.2 MongoDB存储

  1. 存储日志数据
    约束：
  • 日志不可存储SK，ID等敏感内容

6.3 Redis存储

  1. 缓存日志数据
  2. 缓存IAM的查询结果
    约束：
  • 日志不可存储SK，ID等敏感内容

7.安全架构设计

7.1信任边界映射

  • 进入iam-auth-server的通信:不可信
  • 进入iam-api-server的通信：可信
  • Resource Server：半可信
  • MySQL:可信
  • Redis：可信
  • MongoDB：可信
  • iam-operating-system：可信

7.2 凭证保护策略

7.2.1 SK存储策略

本系统采用基于共享密钥的请求签名机制，服务端在受控数据库中保存 Secret Key 以完成请求验签。
鉴于系统部署在受信任内网环境中，数据库访问受严格权限控制，
目前未引入独立密钥管理服务，后续可通过接入 KMS 对密钥存储进行增强。

基本原则

  • 满足 Auth Server 无状态鉴权 的设计约束
  • 支持 Secret 的安全轮换与吊销

鉴权阶段校验流程

  1. 客户端使用SK和请求参数生成客户端签名
  2. 服务端接收请求参数和客户端签名
  3. 服务端使用数据库SK和请求参数生成服务端签名
  4. 服务端校验客户端签名和服务端签名是否相等
  5. 返回鉴权结果

7.2.2 传输安全策略

内部通信安全

IAM 系统组件默认部署在可信内网

内部通信基于以下假设：

  • 网络层隔离
  • 服务身份受控
  • 默认使用 HTTP / gRPC 明文通信

加强防护策略
,在以下场景中应启用加密通信：

  • 跨可用区部署
  • 云环境多租户场景
  • 安全合规要求较高的场景
    可选方案包括：
  • HTTPS（TLS）
  • mTLS（双向证书认证

7.3 防攻击机制概览

本系统的防攻击设计目标是 降低攻击成功概率和提高攻击成功的成本，而非绝对防御。

7.3.1 重放攻击防护

  • 风险描述：攻击者截获合法请求后重复发送，绕过权限校验
  • 防护机制
    • 请求必须包含时间戳
    • Auth Server校验请求时间窗口
    • 过期请求直接拒绝

7.3.2 暴力破解防护

  • 风险描述：攻击者尝试穷举SK或者伪造签名
  • 防护机制：
    • SK具备足够的随机性
    • AK可被独立吊销
    • 支持失败次数统计与告警
    • 可结合网关限流策略

7.3.3 策略绕过防护

  • 风险描述： 策略缺失或者解析失败导致默认方形
  • 防护机制：
    • 默认拒绝原则
    • Policy解析失败即为Deny
    • 不允许隐式授权

7.3.4 内部滥用服务

  • 风险描述：内部组件被滥用或配置错误。
  • 防护机制
    • 控制面与数据面分离
    • Auth Server只有只读权限
    • 所有管理操作可审计

7.3.5 日志与审计

  • 所有鉴权决策生成审计日志
  • 日志支持追溯：
    • Access Key
    • 请求行为
    • 命中策略
  • 日志应异步写入，不影响鉴权性能

8.可扩展性与演进设计

  • Policy版本管理：预计使用Policy存储的扩展字段存储版本信息，若实际性能问题严重，再改数据库表
  • 鉴权策略插件化：未来提供更多版本的鉴权策略，形成策略插件库

9. 接口与通信设计

9.1 接口设计目标

  • 明确分离控制面接口与鉴权接口
  • 避免组件间的职责重叠
  • 为后序Swagger文档与SDK实现提供稳定抽象
  • 支持接口版本化与平滑演进

9.2接口分层与调用关系

9.2.1 控制面接口

  • 提供方:iam-api-server
  • 调用方:
    • iam-auth-server
    • iam-ctl
    • iam-webconsole
    • 管理类SDK
  • 接口风格: RESTful API
  • 核心特征:
    • 有状态的（用户登录态
    • 强一致性
    • 高并发
    • 低延迟
    • 面向人类管理行为

9.2.1 数据面接口/鉴权接口

  • 提供方:iam-auth-server
  • 调用方
    • Resource Server
    • 服务类SDK
  • 接口风格
    • 对外: RESTful API
    • 对内: gRPC调用iam-api-server
  • 核心特征：
    • 无状态的
    • 高并发
    • 低延迟
    • 面向机器调用

9.2.3内部服务接口

  • 提供方:iam-api-server
  • 调用方:
    • iam-auth-server
  • 调用方式：grpc
  • 核心特点：
    • 不对外暴露
    • 保证接口性能和稳定性
    • 不保证向后兼容

9.3 IAM控制面接口抽象

iam-api-server提供的管理接口围绕以下核心资源展开

  • User
  • Secret
  • Policy

接口设计按RESTful API要求的示例如下:

资源 示例路径
User /api/v1/users
Secret /api/v1/secrets
Policy /api/v1/policies

设计约束:

  • IAM管理接口不提供鉴权决策能力
  • IAM管理接口不接受业务请求
  • 所有通过API的写操作必须可审计

9.4 Auth Server数据面接口抽象

即鉴权接口

9.4.1 鉴权接口的最小输入模型

每一次鉴权请求至少包含如下参数

  1. Access Key
  2. 请求方法
  3. 请求路径
  4. 请求时间戳
  5. 请求参数摘要

9.4.2 鉴权接口的响应模型

  • 决策结果
  • 拒绝原因： HTTP code
  • 命中策略信息

9.5 Resource Server接入模式说明

Resource Server为非sup-iam组件，本质同属于第三方服务，必须遵循一下接入模式

  1. 每次受保护请求均需完成鉴权
  2. 逻辑上只与Auth Server交互，对其它iam组件不可见
  3. 不自行解析Policy
  4. 不缓存鉴权决策结果

推荐的接入方式如下：

  • 通过HTTP API调用Auth Server
  • 使用官方SDK

9.6 接口版本管理策略

  1. RESTful API接口使用显式版本号
  2. 鉴权接口保证向后兼容
  3. 内部RPC接口不承诺稳定性

10.非目标与设计限制

  • 本版本不支持 Policy 版本管理
  • 本版本不支持跨 User 的 Secret 共享
  • 所有未在 SAD 中声明的能力均视为非功能需求
  • 本版本暂不开发
    • sup-iam-sdk-go
    • iam-webconsole
    • iamctl
    • iam-operating-system