统一身份认证模块接口定义规范

统一身份认证模块接口定义规范一、总则（一）目的明确。为规范统一身份认证模块接口设计，提升系统互操作性，本规范旨在明确接口定义、数据格式及调用协议，确保各系统间身份信息安全、高效交互。（二）适用范围。本规范适用于所有接入统一身份认证系统的第三方应用、内部业务系统及组件接口开发，涵盖用户认证、授权查询、会话管理及日志审计等核心功能。二、接口分类与编号（一）分类标准。接口按功能划分为认证类、查询类、管理类及日志类四大类别，各类别接口需遵循统一编号规则。（二）编号规则。接口编号采用“模块标识+功能代码+版本号”三级结构，如“UAM-CA-001-V1.0”表示统一身份认证模块认证服务接口V1.0版本。模块标识“UAM”固定，功能代码采用三位字母缩写，版本号按半主次版本号规则递增。三、数据接口规范（一）请求参数。所有接口请求必须包含“method”（方法）、“timestamp”（时间戳）、“sign”（签名）及“app_id”（应用ID）四类基础参数，其中“timestamp”需为UNIX时间戳格式，有效期限制为5分钟。（二）响应格式。接口响应必须包含“code”（状态码）、“message”（提示信息）、“data”（数据体）及“sign”（签名）四类基础字段，状态码采用三位数字编码，如“20001”表示成功，“40001”表示参数错误。（三）数据加密。敏感信息传输必须采用TLS1.2及以上协议加密，密码字段需进行AES-256加密，密钥管理遵循《统一密钥管理规范》执行。四、认证接口详细定义（一）登录认证。接口路径为“/api/auth/login”，采用POST方法提交，请求体包含“username”（用户名）、“password”（密码）及“device_id”（设备标识）字段。成功响应返回“token”（认证令牌）及“expires_in”（有效期）字段。（二）单点登录。接口路径为“/api/auth/sso”，支持POST及GET方法，GET方法需通过“code”参数传递授权码，响应包含“token”及“user_info”字段，用户信息结构见附件A。（三）密码重置。接口路径为“/api/auth/password”，采用POST方法，请求体包含“username”、“mobile”（手机号）及“code”（验证码）字段，验证码有效期30分钟。（四）多因素认证。接口路径为“/api/auth/mfa”，支持短信验证码及动态口令两种方式，调用时需携带“token”参数进行身份校验。五、查询接口详细定义（一）用户信息查询。接口路径为“/api/user/info”，采用GET方法，需通过“Authorization”头传递“token”，响应返回用户基本信息，包括“user_id”、“name”、“department”等字段。（二）权限列表查询。接口路径为“/api/permission/list”，调用时需传递“user_id”及“role_id”参数，返回权限点列表，每个权限点包含“permission_id”、“name”、“code”及“parent_id”字段。（三）会话管理。接口路径为“/api/session/list”，采用GET方法，返回当前用户所有会话记录，包括“session_id”、“ip”、“device”、“login_time”等字段。（四）日志审计。接口路径为“/api/log/audit”，支持分页查询，需传递“user_id”、“start_time”及“end_time”参数，返回操作日志列表，每条日志包含“log_id”、“user_id”、“action”、“time”及“details”字段。六、管理接口详细定义（一）用户管理。接口路径为“/api/user/manage”，采用POST方法，支持新增、修改及禁用用户操作，请求体需包含用户详细信息，如“username”、“password”（加密存储）、“email”等字段。（二）角色管理。接口路径为“/api/role/manage”，采用PUT方法，支持角色权限分配，请求体需包含“role_id”及“permission_ids”字段。（三）API密钥管理。接口路径为“/api/key/manage”，采用POST方法，用于生成及撤销应用API密钥，每个应用密钥有效期默认90天。七、错误码定义（一）通用错误码。10001-10099为接口调用通用错误码，如10001表示参数缺失，10005表示签名校验失败。（二）业务错误码。20001-29999为业务逻辑错误码，如20001表示用户不存在，20005表示密码错误。（三）系统错误码。90001-99999为系统内部错误码，如90001表示服务不可用，90005表示数据库异常。八、安全要求（一）接口鉴权。所有接口必须通过“Authorization”头传递“token”进行身份验证，token生成遵循JWT标准，有效期为24小时。（二）参数校验。所有入参必须进行类型、长度及格式校验，禁止SQL注入等安全风险操作。（三）异常处理。接口发生异常时必须返回500状态码，并包含“code”及“message”字段，禁止抛出系统堆栈信息。九、版本管理（一）版本发布。接口版本号采用“主版本号.次版本号.修订号”格式，主版本号重大变更时需进行兼容性测试。（二）兼容策略。新版本接口发布时，旧版本接口至少支持6个月，期间禁止删除核心字段。十、附则（一）文档更新。本规范由统一身份认证平台运维团队负责维护，每年至少更新一次，重大变更需发布通知公告。（二）责任说明。各接入方需指定接口负责人，确保规