软件需求规格说明书（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 负责对访问请求进行策略评估并返回鉴权决策的服务

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的声明周期

  1. 创建
  2. 绑定
  3. 生效
  4. 过期/手动删除(进入审计)

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

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

6.3.5 Policy的核心属性

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

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

7.1 鉴权请求方与边界

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

7.2 访问请求的基本假设

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

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

  1. 7.3.1请求签名的目的
    1. 防止请求被篡改
    2. 证明请求者持有SK
    3. 支持无状态鉴权
  2. 7.3.2签名所需最小要素
    1. Access Key
    2. 请求时间戳
    3. 请求方法
    4. 请求路径
    5. 请求参数摘要
  3. 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)