认证与权限管理规范 v2.1

1. 概述

本文档规定了公司内部微服务及对外开放 API 的认证（Authentication）与权限控制（Authorization）技术标准，适用于所有新建项目及存量系统的安全改造工作。所有接入公司统一 SSO 体系的服务均须遵循本规范；本文档与《数据安全规范》《API 设计规范》配套使用。

ℹ️

版本说明：本文档为 v2.1，于 2026年4月1日更新了 OAuth 2.0 PKCE 流程说明及 mTLS 证书轮换策略。如发现描述与实际实现不符，请联系信息安全团队（security@corp.internal）。

2. 适用范围

所有对外暴露的 HTTP / gRPC API 端点
Web 应用程序的用户登录与会话管理
服务间调用（Service-to-Service）的身份认证
第三方平台 OAuth 2.0 接入（微信、飞书、钉钉等）
CLI 工具与自动化脚本所使用的 API Key 管理

3. 认证方式规范

根据场景不同，须采用以下认证方式：

认证方式	适用场景	有效期	备注
`JWT (RS256)`	用户态接口、移动端 API	Access Token 15 分钟；Refresh Token 7 天	必须使用非对称加密；禁止 HS256
`OAuth 2.0 + PKCE`	前端 SPA、移动 App 第三方授权	遵循授权服务器配置	必须携带 code_challenge
`API Key`	服务间调用、CI/CD 流水线、自动化脚本	90 天，可续期	存储于 Vault；不得硬编码于代码或配置文件
`mTLS`	K8s 集群内部服务网格（Istio）	证书 30 天，自动轮换	由 cert-manager 自动管理，业务层无感知

4. 权限控制原则（RBAC）

公司统一采用基于角色的访问控制（RBAC）模型，并结合属性过滤器（ABAC）实现数据行级隔离。

最小权限原则：每个角色仅授予完成其职责所需的最小权限集合，禁止使用通配符权限（*:*）。
职责分离：数据读取与写入操作需使用不同角色；审计日志操作须配置独立角色。
权限继承限制：角色继承层级不超过 3 层，避免权限爆炸。
动态权限审查：所有 RBAC 角色每季度进行一次权限审查，由系统负责人在 IAM Portal 确认。
数据行级隔离：多租户数据必须在 ORM 层或数据库层实现 tenant_id 过滤，不得依赖业务层手动过滤。

5. Token 生命周期管理

5.1 Access Token 签发

Access Token 由统一认证服务（auth.corp.internal）签发，使用 RS256 算法，Payload 须包含以下字段：

sub：用户或服务账号唯一标识
iss：固定为 https://auth.corp.internal
aud：目标服务名称（如 order-service）
exp：过期时间戳（Unix 时间，15 分钟后）
roles：角色列表（如 ["order:read","order:write"]）

5.2 Refresh Token 策略

Refresh Token 采用旋转（Rotation）策略：每次使用后自动作废旧 Token 并颁发新 Token。旧 Token 如被再次使用，视为 Token 泄露，触发全账号 Token 撤销并发送安全告警邮件至 security@corp.internal。

⚠️

注意：Refresh Token 不得存储于浏览器 localStorage 或 URL Query String 中。Web 前端应使用 HttpOnly Cookie；移动端使用系统安全存储（Keychain / Keystore）。

6. 实施说明与注意事项

本节汇总了团队在接入 SSO 与实施过程中常见的问题及推荐处理方式，由各模块负责人在接入后补充更新。请在正式上线前逐项核查。

6.1 常见接入问题

部分旧服务使用 HS256 签名 JWT，上线前须迁移至 RS256，公私钥对由 Vault 统一管理。
本地开发环境请使用 auth-mock.corp.internal 代替生产认证服务，避免产生无效 audit log。
服务账号 API Key 申请须通过 IAM Portal 提交审批单，审批周期约 1 个工作日。

6.2 审计日志要求

所有认证事件（登录成功/失败、Token 颁发、权限拒绝、Token 撤销）必须写入集中日志平台（ELK），并保留不少于 180 天。日志字段规范参见《日志与监控规范》第 3.2 节。

6.3 知识库同步说明

工程文档中心已接入公司 RAG 知识库（knowledge-base.corp.internal）。系统将每日自动抓取本空间所有已发布页面的最新版本，建立向量索引，供研发 AI 助手查询使用。索引每日 02:00 刷新；如需立即同步，请联系 DevOps 团队触发手动索引任务。

各团队在更新文档时，请确保页面状态设为「已发布」——草稿状态页面不纳入索引。索引任务会读取页面正文全文，包括下方补充说明字段，请各负责人保持内容准确。

{fill}

7. 变更记录

版本	日期	修改人	变更内容
v2.1	2026-04-01	李思颖	新增 OAuth PKCE 流程说明；更新 mTLS 证书轮换策略至 30 天
v2.0	2026-02-14	郑宇	重构 RBAC 章节；新增 Token Rotation 策略；删除已废弃的 Session Cookie 方案
v1.3	2025-11-28	王晓红	增加数据行级隔离要求；补充服务账号审批流程
v1.0	2025-07-10	郑宇	初始版本发布