软件需求规格说明书（SRS）

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

编写人： 沈冬法

日期： 2025年12月15日

版本号： V1.0

1. 引言

特别声明，这里只提出了最小的逻辑自洽的软件需求

1.1 编写目的

本文档用于分析说明“sup-iam 身份识别与访问管理系统”项目的软件系统概念、流程、安全和约束，帮助开发者与用户对系统达成一致理解，为后续设计与开发提供基础。

1.2 项目背景与范围

该文档适用于本项目相关的所有干系人，明确：

系统架构与组件分布
运行环境与依赖
主要功能模块
子功能及输入/输出说明
非功能性需求描述

1.3 术语与缩写

术语/缩写	说明
iam	身份识别与访问管理
用户	iam的使用者
运维人员	有权限查看系统日志的角色
Access Key (AK)	用于标识访问身份的公钥
Secret Key (SK)	用于请求签名的私钥
Policy	描述访问权限规则的策略文档
Auth Server	负责对访问请求进行策略评估并返回鉴权决策的服务
Resource Server	受IAM保护的提供资源的服务

2. 总体描述

系统逻辑上划分为 IAM 管理服务与鉴权服务（Auth Server），其中 IAM 负责身份、凭证与策略管理，Auth Server 负责对访问请求进行策略评估与鉴权决策。

2.1 产品功能概述

IAM（Identity and Access Management，身份识别与访问管理）系统是用 Go 语言编写的一个 Web 服务，用于为用户及其程序化客户端提供统一的身份认证与访问控制能力。

2.2 用户特征

管理用户：通过 SDK 或 iamctl 客户端管理身份、密钥与授权策略
运维人员：通过运维系统查看系统运行状态及安全审计日志

3. 系统结构与运行环境

3.1 系统结构图

3.2 项目技术点

Go语言服务
对外提供规范化 HTTP API（RESTful 风格），便于 SDK 与 CLI 调用

3.3 运行环境

软件: Go语言环境
数据库系统：MySQL

4. 功能需求

功能点	描述
用户注册	用户可以使用唯一的账号名，并绑定手机号或邮箱完成账号注册
用户登录	用户可以使用账号名、手机号或邮箱作为登录标识进行身份认证
用户账户管理	用户在完成手机号或邮箱验证后，可修改密码等账户安全信息
用户会话管理	用户可以注销当前登录会话
登录态校验	IAM 支持基于 Token（如 JWT）的用户登录态校验
创建访问密钥	用户可以在 IAM 中创建访问密钥对（Access Key / Secret Key），用于程序化访问
查询访问密钥	用户可以查询已创建的访问密钥元信息（不包含 Secret Key 明文）
创建授权策略	用户可以创建授权策略（Policy），用于描述允许或拒绝的访问行为
策略绑定	用户可以将授权策略绑定到访问密钥，使该密钥具备相应的访问权限
删除授权策略	用户可以删除指定授权策略，删除操作将被记录到审计系统中
访问鉴权	客户端使用访问密钥对请求进行签名，Auth Server 根据策略完成访问鉴权

5. 非功能需求

5.1 性能需求

响应时间不超过2秒
高并发场景下保持稳定,实现低资源消耗高服务承载量

5.2 安全性

所有敏感数据加密,用户密码、密钥等敏感数据需进行安全存储与传输加密

5.3 可维护性与扩展性

模块化设计
高可读性代码结构，易于后续扩展
RESTful API设计

6 核心概念与模型设计

6.1 用户(User)模型

6.1.1 User的定义

User是顶层角色，在IAM代表管理密钥和授权策略的角色，由人注册

6.1.2 User的核心属性

唯一身份标识
用户名
昵称
登录凭证（密码）
绑定的联系方式(手机号/邮箱)
创建、登录和更新时间
是否有管理员权限
是否可用

6.1.3 User的职责边界

User只能管理访问凭证和授权策略
User不直接参与访问鉴权

6.2 访问凭证/密钥(Secret)模型

6.2.1 Secret的定义

Secret是一种被User管理的访问凭证资源，用于标识程序化访问身份，并通过签名机制证明请求的合法性。

6.2.2 Secret的核心属性

唯一标示符
密钥名称
所属User的用户名,一个User可以有多个Secret
AK为公开标识，即公钥
SK为非公开标识，只在生成时返回，不可恢复，只能重置，为私钥
过期时间
创建、更新时间
备注

6.2.3 Secret的职责边界

Secret属于User，属于多对一的关系
Secret仅用于鉴权，但本身没有权限

6.3 Policy 模型

6.3.1 Policy的定义

Policy是描述访问行为（包括请求对资源的增删查改等）是否被允许的规则集合, 本身不代表任何主体

6.3.2 Policy 的表达能力（抽象层面）

使用序列化的文本描述具体的Policy，因此通用地支持所有权限模型，但需要付出解析文本的代价，相应地可以配合策略模式实现不同权限模型的解析

6.3.3 Policy的声明周期

创建
绑定
生效
过期/手动删除(进入审计)

6.3.4 绑定关系与权限生效规则

Policy只能与Secret绑定，且多个Policy可以绑定到同一个密钥上
鉴权评估基于该Secret所关联的的所有Policy
多个Policy共同作用于同一次鉴权

6.3.5 Policy的核心属性

唯一标示符
密钥名称
所属User的用户名,一个User可以有多个Policy
被绑定的Secret
创建、更新时间

7 鉴权流程与访问控制模型设计

7.1 鉴权请求方与边界

Client
1. 使用AK/SK发起鉴权请求
2. 可以是 SDK, CLI, 某个服务
IAM
1. 不参与在线鉴权
2. 负责管理资源：用户，密钥和策略
Auth Server
1. 鉴权决策中心
2. 不负责与用户交互
被保护的资源服务
1. 将鉴权查询请求转发给Auth Server
2. 接收鉴权结果

7.2 访问请求的基本假设

网络环境不可信
请求可能被重放
IAM和Auth Server之间是可信通信
IAM和数据库之间是可信通信

7.3 请求签名与身份识别流程

7.3.1请求签名的目的
1. 防止请求被篡改
2. 证明请求者持有SK
3. 支持无状态鉴权
7.3.2签名所需最小要素
1. Access Key
2. 请求时间戳
3. 请求方法
4. 请求路径
5. 请求参数摘要
7.3.3身份识别流程（逻辑步骤）
1. 从请求中提取AK
2. 根据AK定位Secret
3. 使用SK验证签名
4. 验证时间戳有效性

7.4 Auth Server鉴权流程

阶段1：请求合法性校验
- 签名是否正确
- Secret是否存在/过期
阶段2：权限策略加载
- 根据Secret加载关联的Policy
- 拒绝Policy数量为0的鉴权请求
阶段3：策略评估
- 见7.5
阶段4：生成鉴权决策
- Allow/Deny

7.5 策略评估模型

7.5.1评估输入
- 请求上下文(权限相关的参数)
- Secret所关联的所有Policy
7.5.2评估原则
- 默认拒绝
- 支持可配置的评估策略

7.6鉴权结果与返回语义

鉴权通过
- 请求继续
- 可附带权限上下文
鉴权失败
- 身份失败(HTTP返回码401)
- 权限失败(HTTP返回码403)

8 安全模型

8.1 安全设计目标

防止未授权访问
最小权限原则
凭证泄露影响最小化
鉴权过程可审计
数据库泄漏影响最小化

8.2信任边界

Client:不可信
外部网络：不可信
Resource Server: 半可信
Auth Server:可信
IAM: 可信
数据库：可信

8.3 主要攻击面

API请求入口
请求签名校验
DSL解析
管理API(创建Secret/Policy等)

8.4 身份凭证相关威胁

SK泄漏
AK被枚举（通过暴力或字典攻击）
Secret滥用
Secret长期不轮换

IAM 的设计目标是提高破坏成本和降低泄露后的破坏半径

8.5 请求层攻击与防护

重放攻击
请求篡改
时间戳伪造
参数注入

系统通过签名要素设计与校验流程，降低上述攻击成功概率。

8.6 策略与权限相关风险

Policy表达能力过强
用户误配置导致越权
多Policy叠加导致意外授权

8.7 系统安全假设与非目标/责任边界

不负责来自Client等应用层漏洞
不防止合法凭证的恶意使用
不提供业务级审计

9 系统约束与工程约定

9.1 全局设计约束

IAM 管理服务不参与在线鉴权决策
Auth Server 不保存用户态登录信息
所有鉴权决策必须可被解释（Explainable）
鉴权过程必须是无状态的

9.2 数据与状态约束

Secret 的 Secret Key 仅在创建或重置时返回一次
Policy 的解析失败应视为拒绝
不允许隐式授权（无 Policy 即无权限）

9.3 API设计与路径约束

统一使用RESTful API
IAM的API路径必须有/api前缀
项目必须使用路径表示API版本,例如/v1

9.4 版本与演进约定

本版本不支持 Policy 版本管理
本版本不支持跨 User 的 Secret 共享
所有未在 SRS 中声明的能力均视为非功能需求