一、起源:接口暴露带来的信任问题
1.1 三个必须回答的问题
只要接口可以被网络访问,就存在一个不可避免的前提:请求方可能是任何人。后端能做的不是排斥这个前提,而是在每个请求上回答三个问题。
| 问题 | 回答内容 | 未回答的后果 | 主要落地位置 |
|---|---|---|---|
| 谁在调用 | 请求携带的身份凭据是否有效、是否属于当前系统、是否处于有效期内 | 无法区分合法用户与匿名攻击者,匿名请求可直接触发业务写操作 | 2.1 节、2.2 节、3.2 节 |
| 能做什么 | 该身份对目标资源具备哪些权限,范围到接口、方法还是数据行 | 任何已登录用户都能访问全部接口与全部数据,形成越权 | 2.4 节、3.3 节 |
| 如何撤销 | 凭据或权限失效后,多长时间内不再被接受 | 账号停用、密码修改、权限回收后旧凭据仍然可用,问题账号无法及时阻断 | 2.2 节、3.2 节 |
这三个问题之间存在依赖关系:撤销能力取决于凭据的形态,能做什么取决于身份的可信度。因此认证方案的选择不只影响登录功能,还决定了后续授权与止损的可操作空间。
1.2 认证位置的变化:从单体到微服务
单体应用中,认证通常落在同一个进程内:容器维护 HttpSession,业务代码或拦截器从会话中读取当前用户。请求从浏览器直达应用,边界清晰,会话与业务处于同一份内存中,注销即删除服务端记录。Servlet 会话机制的构成见 Java Web 技术体系 第八章。
当系统拆分为多个服务、并引入前端独立部署与多端接入后,认证的位置与形态发生三类变化:
| 变化 | 单体形态 | 拆分后的形态 | 带来的新问题 |
|---|---|---|---|
| 凭据载体 | Cookie 由浏览器自动携带 | 令牌多置于 Authorization 头,由前端显式携带 | 跨域与跨端适配,令牌存储位置成为风险点 |
| 状态存放 | 会话存于应用内存 | 会话集中存储或改为无状态令牌 | 集中存储引入外部依赖;无状态令牌失去即时撤销能力 |
| 校验位置 | 业务进程内统一校验 | 网关、服务、服务间调用分层校验 | 信任边界模糊,内网调用被视为天然可信 |
微服务下的校验位置有三种常见划分方式:
| 方式 | 认证发生位置 | 优势 | 风险 |
|---|---|---|---|
| 网关集中认证 | 网关校验凭据并注入用户信息 | 服务无需重复实现,改造成本低 | 服务若直接暴露则完全无保护;注入的内部头可被伪造 |
| 各服务自校验 | 每个服务独立校验凭据 | 服务边界清晰,可独立部署 | 密钥需分发到所有服务;校验逻辑与配置重复 |
| 网关粗校验加服务细校验 | 网关验凭据,服务验权限与数据范围 | 兼顾成本与最小权限 | 需要明确约定哪些校验只能由服务侧完成 |
内部调用不能因为处于内网就免除鉴权。服务间调用的调用方同样需要身份,常见的做法是内部令牌、双向 TLS 或短期的服务凭据,具体治理手段属于服务治理范畴,见 Spring Cloud 微服务,与本文的接口鉴权在同一层信任模型上衔接。
1.3 常见的安全事故形态
接口暴露后的事故并非都源于复杂漏洞,多数来自校验缺失与凭据管理不当:
| 形态 | 触发条件 | 典型后果 | 对应章节 |
|---|---|---|---|
| 水平越权 | 接口按资源标识查询,未校验归属 | 任意用户可读取、修改他人数据 | 2.6 节、3.3 节 |
| 垂直越权 | 高权限接口只在前端隐藏入口 | 普通用户可直接调用管理接口 | 2.6 节、3.1 节 |
| 令牌泄露 | 令牌写入日志、URL、错误信息或前端可读存储 | 攻击者持有效令牌直接调用接口,日志中难以区分 | 2.7 节、3.5 节 |
| 重放与篡改 | 请求无时间戳、随机数与签名,或校验后可重放 | 同一笔请求被重复提交,金额与数量被改写 | 2.6 节、3.5 节 |
| 会话固定 | 登录成功后未更换会话标识 | 攻击者预置的会话标识在登录后获得用户身份 | 2.1 节 |
| 密钥硬编码 | 签名密钥写入配置或代码仓库 | 密钥泄露后可自行签发任意身份的令牌 | 2.7 节、3.4 节 |
这些形态的共同点是:问题不在业务逻辑本身,而在请求进入业务逻辑之前的信任判定环节。
二、原理
2.1 认证与会话:服务端会话与无状态令牌
认证解决"身份是否成立",会话解决"身份在多次请求之间如何保持"。HTTP 本身无状态,两次请求之间没有任何关联,因此需要一种显式的状态延续机制。
基于 Cookie 与 Session 的服务端会话
容器在首次请求时创建会话对象并分配标识,通过 Set-Cookie 下发,后续请求由浏览器自动携带,容器据此找到会话记录。凭据本身只是一个随机标识,用户身份保存在服务端。
- 状态位置:服务端内存或集中存储
- 撤销能力:删除服务端记录即生效,可精确到单个会话
- 扩展方式:多节点需要会话粘性、会话复制或集中存储,见 Java Web 技术体系 第 8.2 节
- 攻击面:Cookie 由浏览器自动携带,跨站请求会附带凭据,天然存在 CSRF 风险
基于令牌的无状态会话
服务端签发一个自包含的令牌,令牌内部携带身份与过期信息,并由服务端签名。后续请求携带该令牌,服务端只需验签与检查声明,不查询任何存储。
- 状态位置:客户端持有,服务端不保存
- 撤销能力:校验过程不访问服务端,因此无法即时失效,只能依靠短有效期与补偿机制
- 扩展方式:任意节点持有验签公钥即可校验,水平扩展无额外依赖
- 攻击面:令牌一旦泄露,在有效期内等同于有效凭据;令牌存放位置的 XSS 暴露面大于 Cookie
两种方案在工程维度上的对比:
| 维度 | 服务端会话 | 无状态令牌 |
|---|---|---|
| 状态存放 | 服务端 | 客户端 |
| 多节点扩展 | 需要粘性、复制或集中存储 | 无需共享状态 |
| 跨域与多端 | Cookie 受同源策略约束,移动端适配差 | 头部携带,跨端一致 |
| 即时撤销 | 支持 | 需黑名单或版本号补偿 |
| 单点故障 | 集中存储成为依赖 | 验签密钥成为依赖 |
| CSRF 暴露 | 存在 | 使用自定义头时基本消除 |
| 令牌体积 | 标识很小 | 自包含声明,体积较大 |
取舍结论不是二选一,而是按场景划分:管理后台等浏览器场景可用服务端会话,依靠集中存储与 CSRF 防护;面向多端与跨系统的 API 场景更适合无状态令牌;两者并存时需明确各入口的凭据类型,避免同一套放行规则同时接受两种凭据。
会话固定与注销语义
会话固定(Session Fixation)的成因是会话标识在登录前后不发生变化:攻击者先获取一个合法会话标识,诱导受害者使用该标识完成登录,此后该标识即代表受害者身份。防护方式是登录成功后立即更换会话标识,Spring Security 的默认策略会在认证成功时迁移会话。
注销语义在两种方案下并不相同:
| 方案 | 客户端动作 | 服务端动作 | 注销后令牌是否仍可用 |
|---|---|---|---|
| 服务端会话 | 清除 Cookie | 删除会话记录 | 否,记录已不存在 |
| 无状态令牌(仅客户端丢弃) | 丢弃令牌 | 无 | 是,令牌在有效期内仍可被第三方使用 |
| 无状态令牌(含补偿) | 丢弃令牌 | 写入黑名单或递增令牌版本 | 否,校验时命中黑名单或版本不一致 |
因此无状态令牌的注销必须包含服务端动作,否则"退出登录"只是前端表现层的动作,凭据仍然有效。
2.2 JWT 的结构与生命周期
结构
JWT 由三段以点分隔的字符串组成:头部、载荷、签名。
base64url(header) . base64url(payload) . base64url(signature)
header = {"alg":"RS256","kid":"2026-09","typ":"JWT"}
payload = {"iss":"https://auth.example.com","sub":"10086","aud":"order-service",
"iat":1758000000,"exp":1758000900,"jti":"9f1c...","ver":3,
"scope":["order:read"]}
signature = sign(base64url(header) + "." + base64url(payload), privateKey)
头部与载荷使用 Base64URL 编码而非加密,任何人拿到令牌都可以解出其中的声明。签名只保证内容未被篡改,不保证内容不可见。因此载荷中不应放置口令、身份证号、手机号等敏感信息。
签名算法与对称、非对称的取舍
| 算法族 | 代表算法 | 密钥形态 | 验签方需要 | 适用 |
|---|---|---|---|---|
| 对称 | HS256、HS384 | 单一共享密钥 | 持有同一密钥即可签发与验签 | 单一服务自签自验,密钥不离开该服务 |
| 非对称 | RS256、ES256 | 私钥签名,公钥验签 | 仅需公钥 | 多服务验签、第三方接入、公钥可公开分发 |
对称算法的风险在于密钥的双向能力:任何持有密钥的组件都能签发令牌。当验签方数量增加、或存在外部系统需要验证令牌时,非对称算法可以把签发能力收敛到授权服务器,验签方仅持公钥。非对称算法的代价是签名与验签耗时更高、令牌体积更大,可通过控制声明数量缓解。
有效期与刷新令牌机制
访问令牌的有效期是"泄露后可被利用的时间窗口"与"撤销补偿成本"之间的权衡:有效期越短,泄露窗口越小,但客户端需要更频繁地获取新令牌。
常见分工是双令牌结构:
- 访问令牌:有效期数分钟到数十分钟,随每次业务请求携带,校验不查存储
- 刷新令牌:有效期数天,仅在换取访问令牌时使用,服务端保存其记录以便撤销
刷新令牌需要轮换(rotation):每次刷新签发新的刷新令牌并作废旧的。若已作废的刷新令牌再次被使用,说明发生了重放,此时应撤销该用户全部刷新令牌并告警。
主动失效的实现难度与补偿手段
无状态校验不访问服务端,因此不存在"删除记录即失效"的能力。可用的补偿手段有三类:
| 手段 | 实现方式 | 生效延迟 | 代价 |
|---|---|---|---|
| 黑名单 | 记录已注销令牌的 jti,TTL 与令牌剩余有效期一致 | 立即 | 校验时增加一次存储查询;键数量与注销频率相关 |
| 令牌版本号 | 用户维度维护版本号,令牌携带签发时的版本,校验时比对 | 立即 | 每次校验需读取用户版本;版本变更后该用户全部令牌失效 |
| 短有效期 | 缩短访问令牌有效期,靠自然过期收敛 | 最长等于有效期 | 刷新频率升高,刷新接口压力增大 |
三种手段常组合使用:短有效期作为基础,版本号用于账号级止损(改密、停用、强制下线),黑名单用于单令牌级注销。仅依靠短有效期的方案无法应对账号被盗等需要立即止损的场景。
常见错误用法
| 错误用法 | 问题 | 后果 |
|---|---|---|
| 载荷中放敏感信息 | 编码不等于加密,内容可被解出 | 个人信息与内部标识泄露 |
从头部读取 alg 决定验签算法 | 攻击者可声明 none 或把 RS256 改为 HS256 并用公钥作对称密钥 | 令牌被伪造 |
不校验 iss、aud | 其他系统签发的令牌在该系统同样通过校验 | 跨系统越权 |
| 有效期设置过长或永不过期 | 撤销手段的窗口被放大 | 泄露令牌长期可用 |
| 把权限明细全部写入令牌且不设版本 | 权限回收后令牌中的权限声明仍然有效 | 已回收的权限继续可用 |
| 令牌与业务数据混用 | 把令牌当作会话数据容器,持续追加字段 | 令牌体积膨胀,头部超出服务端限制 |
2.3 OAuth2 与 OIDC
OAuth2 是授权框架,解决的是"在用户不向第三方应用提供口令的前提下,让第三方应用代表用户访问资源";OIDC 在 OAuth2 之上增加身份层,解决"第三方应用如何确认用户身份"。
角色
| 角色 | 职责 |
|---|---|
| 资源所有者 | 授权的主体,通常为用户 |
| 客户端 | 申请访问资源的应用 |
| 授权服务器 | 认证用户、颁发令牌、提供密钥与元数据 |
| 资源服务器 | 校验令牌并保护资源,可独立于授权服务器部署 |
授权类型与适用边界
| 授权类型 | 使用方 | 是否携带用户身份 | 适用与边界 |
|---|---|---|---|
| 授权码加 PKCE | 前端应用、移动端、服务端应用 | 是 | 通用推荐方式,公开客户端必须使用 PKCE |
| 客户端凭证 | 服务端到服务端 | 否 | 无用户上下文的后台任务与系统间调用 |
| 刷新令牌 | 已获授权的客户端 | 沿用原授权 | 用于换取新的访问令牌,需轮换与撤销能力 |
| 密码模式 | 客户端直接收集用户口令 | 是 | 已废弃,口令暴露给客户端并破坏授权语义,仅存量系统兼容 |
| 隐式模式 | 令牌直接从授权端点返回 | 是 | 已废弃,令牌暴露在 URL 与浏览器历史中 |
授权码流程与 PKCE
核心前提是令牌不经过浏览器,浏览器只传递一次性的授权码,客户端再用授权码与自身凭据向授权服务器换取令牌。
1. 客户端生成 code_verifier,计算 code_challenge = BASE64URL(SHA256(code_verifier))
2. 浏览器重定向到授权端点,携带 client_id、redirect_uri、scope、state、code_challenge
3. 用户在授权服务器完成认证与授权
4. 授权服务器重定向回 redirect_uri,携带 authorization_code 与 state
5. 客户端校验 state,再用授权码 + code_verifier 调用令牌端点
6. 授权服务器校验 code_verifier 与 code_challenge 匹配后颁发令牌
PKCE 解决的是公开客户端无法安全保管 client_secret 的问题:授权码即使被截获,缺少 code_verifier 也无法换取令牌。state 参数用于防 CSRF 与关联请求,OIDC 另用 nonce 关联 id_token 与授权请求。
令牌自省与用户信息端点
资源服务器拿到令牌后有两种校验路径:
| 路径 | 机制 | 特点 |
|---|---|---|
| 本地校验 | 通过 JWKS 端点获取公钥,本地验签并检查声明 | 无网络往返,需处理密钥缓存与轮换 |
| 令牌自省 | 调用授权服务器的自省端点,返回令牌是否有效及元数据 | 结果最权威,支持不透明令牌,但每次校验产生一次调用 |
两种路径可组合:常规请求走本地校验,敏感操作额外调用自省确认令牌未被撤销。用户信息端点用于以访问令牌换取用户属性,其边界是只返回身份相关字段,不应作为权限判断的唯一依据。
单点登录的落地方式
单点登录的基本结构是:授权服务器持有全局会话(通常为 Cookie),各应用不直接共享会话,而是通过授权码流程或后端通道获取身份,再在本应用内建立自己的会话或令牌。因此各应用与授权服务器之间的信任由令牌与公钥承担,而不是由共享会话承担。会话失效需要在授权服务器侧执行,各应用的本地会话则依靠较短的本地有效期或单点注销通道收敛。
2.4 授权模型
认证回答身份,授权回答该身份能做什么。二者不可互相替代:合法的登录者同样可能越权。
角色、权限与资源的关系
| 概念 | 含义 | 示例 |
|---|---|---|
| 主体 | 发起操作的身份 | 用户、服务账号 |
| 角色 | 权限的集合,用于批量授予 | 订单管理员 |
| 权限 | 对某类操作或资源的许可 | order:read、order:export |
| 资源 | 被操作的对象 | 订单、报表、用户资料 |
RBAC 与 ABAC 与数据权限的差别
| 模型 | 判定依据 | 表达能力 | 局限 |
|---|---|---|---|
| RBAC | 主体是否具备角色或权限 | 适合功能级权限,规则集中易管理 | 无法表达"只能看本部门数据"这类条件 |
| ABAC | 主体属性、资源属性、环境条件共同决定 | 表达能力强,可覆盖时间、来源、数据敏感级别 | 规则复杂,策略维护与冲突检测成本高 |
| 数据权限 | 主体可见的数据范围(本人、本部门、本部门及下级、全部) | 直接作用于数据行集合 | 需要与查询逻辑结合,遗漏一处即产生越权 |
工程中的常见组合是:接口与方法层用 RBAC 做功能级控制,查询层用数据权限限定行范围,个别高风险操作(如跨境访问、非工作时间导出)用 ABAC 规则补强。
方法级、接口级与数据级三层校验
| 层次 | 校验对象 | 典型手段 | 遗漏后果 |
|---|---|---|---|
| 接口级 | URL 与方法 | 过滤器链的路径匹配规则 | 未匹配的接口默认放行或默认拒绝,取决于配置 |
| 方法级 | 具体业务方法 | 方法注解与权限表达式 | 新增接口未声明权限即暴露给全部已认证用户 |
| 数据级 | 查询与写入涉及的数据行 | 归属校验、数据范围条件注入 | 功能权限正确但可跨用户、跨部门访问数据 |
三层需要同时成立。仅做接口级校验时,同一接口内的不同业务动作通常需要不同权限;仅做接口级与方法级校验时,水平越权仍然存在。
权限缓存的失效时机
权限判定在每次请求上执行,若每次都访问数据库会形成明显压力,因此权限与角色关系通常需要缓存。缓存带来的问题是变更可见性,需要明确四类失效触发点:
- 角色权限关系变更(为角色增删权限)
- 用户角色关系变更(为用户增删角色)
- 用户状态变更(停用、冻结、离职)
- 组织架构调整(部门迁移,影响数据范围)
失效方式有三种:变更时直接删除对应缓存键、递增全局或用户维度的权限版本号、设置较短 TTL 作为兜底。删除类失效依赖变更路径完整(所有写入入口都调用失效逻辑),版本号类失效对遗漏更宽容但每次校验需要读取版本,两者叠加短 TTL 是最稳妥的组合。
2.5 Spring Security 机制
过滤器链的构成与执行顺序
Spring Security 通过一个 Servlet 过滤器接入容器:DelegatingFilterProxy 把容器的过滤器调用委托给 Spring 容器中的 FilterChainProxy,后者再按配置的 SecurityFilterChain 依次执行内部过滤器。多个 SecurityFilterChain 可按路径匹配,命中第一条即返回,因此链的定义顺序决定匹配优先级。
链中过滤器的职责分工(以 Spring Security 6 的常见顺序为例):
| 顺序 | 过滤器 | 职责 |
|---|---|---|
| 1 | DisableEncodeUrlFilter / WebAsyncManagerIntegrationFilter | 关闭 URL 重写携带会话标识;把安全上下文与异步请求关联 |
| 2 | SecurityContextHolderFilter | 从存储中加载安全上下文并在请求结束后清理 |
| 3 | HeaderWriterFilter / CorsFilter | 写入安全响应头;处理跨域预检与实际请求 |
| 4 | LogoutFilter | 处理注销请求 |
| 5 | UsernamePasswordAuthenticationFilter / 自定义令牌过滤器 | 从表单、令牌或自定义凭据构造未认证的认证对象 |
| 6 | RequestCacheAwareFilter / SecurityContextHolderAwareRequestFilter | 恢复被拦截的请求;包装请求对象提供安全相关方法 |
| 7 | AnonymousAuthenticationFilter | 为未认证请求填充匿名身份,避免空指针判定 |
| 8 | ExceptionTranslationFilter | 捕获认证与授权异常,分别交给认证入口与拒绝处理器 |
| 9 | AuthorizationFilter | 执行授权判定,拒绝时抛出访问拒绝异常 |
自定义令牌过滤器通常插入在第 5 位附近(UsernamePasswordAuthenticationFilter 之前),使其解析出的认证结果能够被后续的授权过滤器使用。过滤器、拦截器与 AOP 的分层关系与适用场景见 Java Web 技术体系 第 5.4 节;切面的代理机制与内部调用失效原理见 Spring Framework 核心体系 第三章。
认证管理器与认证提供者
AuthenticationManager 负责认证入口,默认实现 ProviderManager 持有一组 AuthenticationProvider,按提供者支持的认证对象类型依次尝试,任一提供者成功即返回。表单登录场景中,DaoAuthenticationProvider 通过 UserDetailsService 加载用户、通过 PasswordEncoder 校验口令。
认证对象包含三部分:凭据(principal)、凭证(credentials)与权限集合(authorities)。需要特别注意的是,Authentication 中的 authorities 代表认证结果携带的权限,它既可以来自令牌声明,也可以来自服务端查询;当权限来自令牌声明时,权限回收的生效时间受令牌有效期约束。
安全上下文与上下文传播
认证成功后,结果被写入 SecurityContextHolder。默认策略是 MODE_THREADLOCAL,即以线程局部变量保存,其含义是:
- 同一请求线程内可随处读取当前身份
- 新线程不会继承安全上下文,
@Async、线程池、CompletableFuture中的代码读取到的上下文为空 - 请求结束后上下文被清理,不残留到复用的线程上
跨线程传播的常用做法有四种:
| 做法 | 机制 | 适用 |
|---|---|---|
MODE_INHERITABLETHREADLOCAL | 子线程继承创建时刻的上下文 | 手动创建线程的场景,线程池下不可靠 |
DelegatingSecurityContextRunnable / Callable | 包装任务,执行前设置、执行后清理 | 直接提交任务的场景 |
DelegatingSecurityContextExecutor | 包装线程池,自动完成上述包装 | @Async 之外的线程池任务 |
DelegatingSecurityContextAsyncTaskExecutor | 替换异步执行器 | @Async 方法需要读取身份时 |
异步场景的另一类问题是上下文读取时机:若在异步方法内部才读取上下文,需要执行器已正确包装;若在主线程读取身份后以参数传递,则可避免对上下文的依赖,这类方案在审计日志与数据权限判定中更为稳妥。
CSRF 与 CORS 的处理
两者常被混为一谈,实际针对不同威胁:
| 机制 | 针对的威胁 | 判定依据 | 与凭据形态的关系 |
|---|---|---|---|
| CSRF 防护 | 浏览器自动携带凭据导致的跨站伪造请求 | 请求中是否存在服务端下发的 CSRF 令牌、来源是否可信 | 使用 Cookie 会话时必须启用 |
| CORS 配置 | 浏览器同源策略下跨源请求的许可范围 | 响应头中的允许来源、方法、是否允许携带凭据 | 与凭据形态无关,属于浏览器侧访问控制 |
两点需要明确:
- 无状态令牌模式(凭据置于自定义请求头、不使用 Cookie)通常可以关闭 CSRF 防护,原因是自定义头不会由浏览器自动附加,跨站页面无法构造该请求。但如果同时存在 Cookie 会话入口,则不能关闭。
- CORS 中允许携带凭据(
allowCredentials)时,允许来源不能为通配符,必须列出具体来源;否则浏览器会拒绝该响应,或浏览器配置放宽后造成凭据被任意来源携带。
密码编码器的选择
口令在服务端只应保存不可逆的哈希,且哈希算法需要具备两个特性:随算力提升可调高成本、每个口令使用独立盐值。
| 编码器 | 特性 | 建议 |
|---|---|---|
BCryptPasswordEncoder | 自适应成本因子,内置随机盐 | 默认选择,成本因子按硬件性能上调 |
Argon2PasswordEncoder | 抗 GPU 并行,内存与时间成本可调 | 安全要求较高时选择,需额外依赖 |
Pbkdf2PasswordEncoder | 标准算法,迭代次数可调 | 受合规要求指定算法时使用 |
DelegatingPasswordEncoder | 密文中携带算法标识,支持多算法共存与迁移 | 存量系统升级时使用,便于逐步替换 |
MD5、SHA-1 加盐或加固定盐、可逆加密保存口令均不满足口令存储要求。口令校验的比较过程应使用恒定时间比较,避免通过响应时间差异推测口令内容。
2.6 越权与常见攻击
水平越权与垂直越权
| 类型 | 定义 | 典型触发方式 | 判定要点 |
|---|---|---|---|
| 水平越权 | 同权限级别的用户访问他人的数据 | 修改请求中的资源标识 | 资源与当前身份是否存在归属关系 |
| 垂直越权 | 低权限身份执行高权限操作 | 直接调用管理接口或修改权限参数 | 当前身份是否具备该操作的权限 |
水平越权的判定必须在服务端完成,因为资源标识完全由客户端提供;垂直越权的判定必须覆盖全部入口,因为前端隐藏只是界面行为。
越权的常见代码形态
| 代码形态 | 问题 | 修正方向 |
|---|---|---|
selectById(id) 后直接返回 | 未校验资源归属 | 查询条件中带上归属约束,或查询后做归属判定 |
| 前端隐藏按钮或路由守卫代替后端校验 | 接口本身无权限判定 | 服务端补权限判定,前端控制只作为体验优化 |
| 权限判断写在 Controller,Service 被其他入口复用 | 绕过 Controller 的调用路径无校验 | 校验下沉到 Service,或保证所有入口都经过校验 |
| 批量接口只校验整体权限,不逐个校验资源 | 混入无权限资源即可越权 | 逐条校验归属,或按范围条件过滤后处理 |
| 导出与下载接口遗漏鉴权 | 导出接口的参数直接对应数据范围 | 导出接口与列表接口使用同一套数据范围逻辑 |
| 内部接口不加鉴权依赖网络隔离 | 网络边界一旦被绕过即完全暴露 | 内部接口同样鉴权,使用内部凭据 |
重放与篡改
重放是两个不同层次的问题:一是同一请求被重复提交(重复下单、重复扣款),二是请求参数被篡改后仍然通过校验。
防护手段分两类:
| 目标 | 手段 | 要点 |
|---|---|---|
| 防重复提交 | 幂等键、唯一约束、状态条件更新 | 幂等能力的最终保障在存储层,令牌或缓存占位只用于降低压力 |
| 防参数篡改 | 对关键参数计算签名(HMAC),服务端重新计算并比对 | 密钥不下发到客户端,签名需覆盖时间戳与随机数 |
| 防重放 | 时间戳窗口加随机数(nonce)去重 | 窗口越大容忍度越高,去重记录需设置与窗口一致的过期时间 |
在令牌场景中,重放的成本取决于令牌泄露窗口与接口幂等性。仅依赖令牌本身无法防重放,因为合法令牌发起的重复请求在形式上完全合法。
CSRF、XSS、SSRF 与注入的防护要点
| 攻击 | 作用机制 | 防护要点 |
|---|---|---|
| CSRF | 诱导浏览器携带 Cookie 发起状态变更请求 | 下发并校验 CSRF 令牌、设置 Cookie 的 SameSite、校验来源头 |
| XSS | 页面注入脚本,读取页面可访问的数据并以用户身份发起请求 | 输出转义、富文本白名单过滤、内容安全策略、令牌不置于脚本可读的存储 |
| SSRF | 服务端按参数发起请求,被指向内部地址 | 目标地址白名单、限制协议与端口、禁止访问内网与元数据地址、禁止跟随重定向 |
| SQL 注入 | 参数拼接进 SQL 语句 | 全部使用参数绑定,动态表名与排序字段用白名单映射 |
| 表达式注入 | 用户输入进入 SpEL、OGNL 等表达式引擎 | 不使用用户输入作为表达式,必要场景使用受限上下文与白名单 |
| 反序列化 | 恶意字节流在还原对象时触发危险方法 | 不接收不可信来源的原生序列化数据,具体攻击面见 序列化与反序列化 第 5.2 节与第七章 |
接口枚举与限流
登录、注册、找回口令、短信验证码等接口存在两类风险:一是通过错误信息差异判断账号是否存在(例如"用户不存在"与"密码错误"分别返回),二是被批量尝试口令或验证码。防护要点是统一错误信息与响应时间、对同一账号与同一来源分别计数、对验证码与口令尝试设置逐步加长的冷却时间。限流的算法选择、过期时间设置与服务端时间源统一等实现细节见 Redis 缓存实践与常见问题 第 2.3 节。
2.7 密钥与凭据管理
认证体系的安全强度最终落在密钥上:签名密钥泄露等价于任意身份可被伪造,口令哈希参数过弱等价于口令可被离线破解。
签名密钥的生成与轮换
| 算法族 | 生成要求 | 轮换方式 |
|---|---|---|
| HS256 | 使用密码学安全随机源生成,长度不小于哈希输出长度 | 新旧密钥并行校验,切换签发后再停用旧密钥 |
| RS256 | RSA 密钥长度不低于 2048 位 | 新密钥对上线后按 kid 并行校验,观察窗口结束后下线旧公钥 |
| ES256 | 使用推荐曲线(如 P-256) | 同上 |
轮换的通用流程依赖 kid(密钥标识):令牌头部声明签发所用的 kid,验签方据此选择对应公钥。因此轮换期间可以同时存在多个有效公钥,先让验签方识别新公钥,再切换签发使用的私钥。
对称密钥的存储位置
| 存储位置 | 特点 | 适用 |
|---|---|---|
| 硬编码在代码或配置文件中 | 随代码仓库扩散,无法区分环境 | 不应使用 |
| 环境变量 | 与镜像解耦,需配合编排平台的密钥管理 | 常规部署方式 |
| 配置中心 | 统一管理,可按环境隔离,需保护配置中心自身的访问权限 | 多环境多服务 |
| 密钥服务(KMS、Vault 类系统) | 密钥不落地,可审计访问、可集中轮换 | 安全要求较高的生产环境 |
配置项的注入方式与敏感配置的分层处理见 Spring Boot application.yml 核心配置 第六章与 企业级项目实践指导手册 第 2.3 节。
令牌与密钥的泄露应急处置
泄露的处置顺序是先止损再定位:确定泄露范围(哪些密钥、哪些令牌、泄露时长)、更换受影响的密钥、使受影响的令牌失效、再回溯访问记录确认是否已被利用。密钥更换会使所有已签发令牌同时失效,属于影响面较大的操作,需要在变更窗口内执行并预先通知。
2.8 审计与合规
认证授权系统的运行痕迹同时承担两项职责:一是支撑故障排查与安全事件回溯,二是满足合规对访问控制与操作留痕的要求。
需要留痕的事件
| 事件类型 | 记录内容 | 用途 |
|---|---|---|
| 登录成功 | 账号、时间、来源地址、客户端标识、认证方式 | 建立访问基线,识别异常来源 |
| 登录失败 | 账号、时间、来源地址、失败原因类别 | 识别暴力破解与账号枚举 |
| 注销与令牌撤销 | 账号、令牌标识、撤销原因 | 解释"为何该凭据立即失效" |
| 令牌签发与刷新 | 账号、客户端标识、签发时间、有效期 | 追溯凭据来源与生命周期 |
| 授权变更 | 操作者、目标账号、变更前后权限、变更时间 | 权限审计与越权追溯 |
| 敏感操作 | 操作者、对象、结果、请求标识 | 事后追责与影响面评定 |
日志脱敏
认证相关日志最容易成为泄露渠道,需要显式约束:口令、令牌、刷新令牌、验证码、会话标识不写入日志;令牌如需关联,只记录其哈希前缀或 jti;个人信息按最小必要记录。统一异常处理中输出的错误信息同样不应包含内部类名、SQL 语句与堆栈细节。
留存期限与证据完整性
留存期限由合规要求、事件发现周期与查询需求共同决定;防篡改强度从集中转发、权限收敛与仅追加属性,到独立存储与完整性校验递进。审计三要素(主体、动作、时间)与证据链的可关联、不可否认、可验证、可重建要求,以及留存期限的确定方式与日志删除的处置口径,见 Linux 合规与审计落地 第 2.2 节与第 2.4 节。主机侧的登录审计、提权审计与失败登录排查方式见 Linux 主机加固与登录安全 第 1.8 节与第 1.12 节。
应用层审计与主机层审计需要在同一时间线上关联:应用日志记录"谁调用了哪个接口",主机日志记录"谁登录了哪台主机、执行了什么命令",两者时间源需要统一,否则多源记录无法对齐。
三、实现
3.1 过滤器链配置实践
无状态配置与认证入口
@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig {
@Bean
SecurityFilterChain apiSecurityFilterChain(HttpSecurity http,
JwtAuthenticationFilter jwtFilter,
RestAuthenticationEntryPoint entryPoint,
RestAccessDeniedHandler deniedHandler) throws Exception {
http
// 凭据置于 Authorization 头,不使用 Cookie 会话,因此关闭 CSRF
.csrf(AbstractHttpConfigurer::disable)
.cors(Customizer.withDefaults())
.formLogin(AbstractHttpConfigurer::disable)
.httpBasic(AbstractHttpConfigurer::disable)
.sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
.authorizeHttpRequests(auth -> auth
.requestMatchers("/api/auth/login", "/api/auth/refresh", "/actuator/health").permitAll()
.requestMatchers("/api/admin/**").hasRole("ADMIN")
.anyRequest().authenticated())
.exceptionHandling(e -> e
.authenticationEntryPoint(entryPoint) // 未认证或凭据无效 → 401
.accessDeniedHandler(deniedHandler)) // 已认证但无权限 → 403
.addFilterBefore(jwtFilter, UsernamePasswordAuthenticationFilter.class);
return http.build();
}
@Bean
PasswordEncoder passwordEncoder() {
return new BCryptPasswordEncoder(12);
}
}
认证入口与拒绝处理器需要返回稳定的响应结构,使调用方能够区分"需要重新登录"与"权限不足",同时不泄露内部判定细节:
@Component
public class RestAuthenticationEntryPoint implements AuthenticationEntryPoint {
@Override
public void commence(HttpServletRequest request, HttpServletResponse response,
AuthenticationException ex) throws IOException {
response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
response.setContentType("application/json;charset=UTF-8");
response.getWriter().write("{\"code\":\"UNAUTHENTICATED\",\"message\":\"认证信息无效或已过期\"}");
}
}
@Component
public class RestAccessDeniedHandler implements AccessDeniedHandler {
@Override
public void handle(HttpServletRequest request, HttpServletResponse response,
AccessDeniedException ex) throws IOException {
response.setStatus(HttpServletResponse.SC_FORBIDDEN);
response.setContentType("application/json;charset=UTF-8");
response.getWriter().write("{\"code\":\"FORBIDDEN\",\"message\":\"无权访问该资源\"}");
}
}
HTTP 状态码的语义分工(401 表示未认证、403 表示已认证但无权限)见 HTTP API 的基本组成章节。
高危:关闭 CSRF 校验(上例中的 csrf(AbstractHttpConfigurer::disable))会去除对跨站伪造请求的校验,影响范围为全部使用 Cookie 或由浏览器自动携带凭据的入口。当系统同时存在 Cookie 会话与令牌两种入口时,关闭后 Cookie 入口可被任意站点伪造发起写操作。回滚方式:仅在确认全部入口的凭据均由自定义请求头显式携带、不存在任何 Cookie 会话登录时才保持关闭;一旦存在 Cookie 入口,需恢复 CSRF 校验并同步下发令牌,或为两种入口分别定义过滤器链并仅对令牌入口关闭。
放行规则的白名单管理
白名单散落在代码各处会导致两类问题:新增接口时误判是否已放行、审计时难以确认当前实际放行范围。
security:
auth:
# 白名单集中声明,便于审计与评审;变更需走变更流程
white-list:
- /api/auth/login
- /api/auth/refresh
- /actuator/health
- /doc.html
@ConfigurationProperties(prefix = "security.auth")
public class AuthWhitelistProperties {
private List<String> whiteList = new ArrayList<>();
// getter / setter
}
规则匹配需注意两点:路径匹配方式(Ant 风格与 MVC 风格对通配符的处理不同)应统一;通配符的范围要逐条确认,/api/admin/** 与 /api/** 的影响面差别很大。
高危:放宽放行规则(新增白名单、把路径匹配改为更宽的通配符、临时对某前缀 permitAll)会直接扩大未认证可访问的接口范围,一旦命中的接口包含写操作,等同于匿名可写。影响范围为全部匹配该规则且无其他校验入口的接口。回滚方式:白名单与匹配规则纳入配置管理并保留历史版本,变更后立即用未携带凭据的请求逐个探测新放行的路径确认返回 401,发现范围超出预期时回退配置并重启或刷新配置。
接口粒度的权限注解
@RestController
@RequestMapping("/api/order")
public class OrderController {
@PreAuthorize("hasAuthority('order:read')")
@GetMapping("/{id}")
public OrderVO detail(@PathVariable long id) { ... }
@PreAuthorize("hasAuthority('order:export') and @perm.dataScopeAllowed('order', #query)")
@PostMapping("/export")
public void export(@RequestBody OrderQuery query, HttpServletResponse response) { ... }
}
方法级注解的判定依赖 Authentication 中的 authorities,因此 authorities 的来源决定权限变更的生效时间:来自令牌声明时受令牌有效期约束,来自服务端查询时受权限缓存 TTL 约束。
3.2 令牌实现要点
签发与校验的代码结构
签发阶段遵循最小声明原则,只写入校验与授权必需的字段:
public String issueAccessToken(UserPrincipal principal) {
Instant now = Instant.now();
return Jwts.builder()
.header().keyId(keyProvider.currentKeyId()).and()
.issuer(ISSUER)
.subject(String.valueOf(principal.getUserId()))
.audience().add(AUDIENCE).and()
.issuedAt(Date.from(now))
.expiration(Date.from(now.plus(accessTtl)))
.id(UUID.randomUUID().toString()) // jti:用于黑名单定位
.claim("ver", principal.getTokenVersion()) // 版本号:用于账号级止损
.signWith(keyProvider.signingKey(), Jwts.SIG.RS256) // 算法固定,不由配置动态决定
.compact();
}
校验阶段的两个关键约束是算法固定与声明完整校验:
public Claims parse(String token) {
String kid = readKeyIdUnverified(token); // 头部仅用于选择验签密钥
PublicKey key = keyProvider.publicKey(kid); // kid 未知则直接失败,不做算法回退
return Jwts.parser()
.verifyWith(key) // 验签算法由密钥类型决定
.requireIssuer(ISSUER)
.requireAudience(AUDIENCE)
.clockSkewSeconds(60) // 容许集群内的时钟偏差
.build()
.parseSignedClaims(token)
.getPayload();
}
过滤器内还需校验版本号与黑名单,并把结果写入安全上下文:
@Component
public class JwtAuthenticationFilter extends OncePerRequestFilter {
@Override
protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
FilterChain chain) throws ServletException, IOException {
String header = request.getHeader(HttpHeaders.AUTHORIZATION);
if (header != null && header.startsWith("Bearer ")) {
String token = header.substring(7);
try {
Claims claims = jwtService.parse(token);
long userId = Long.parseLong(claims.getSubject());
if (tokenStateService.isRevoked(claims.getId())
|| tokenStateService.versionMismatch(userId, claims.get("ver", Integer.class))) {
throw new CredentialsExpiredException("token revoked");
}
Authentication auth = new JwtAuthenticationToken(
new UserPrincipal(userId), token, authorityService.authoritiesOf(userId));
SecurityContext context = SecurityContextHolder.createEmptyContext();
context.setAuthentication(auth);
SecurityContextHolder.setContext(context);
} catch (JwtException | IllegalArgumentException e) {
SecurityContextHolder.clearContext(); // 凭据无效时不放行,交由入口返回 401
}
}
chain.doFilter(request, response);
}
}
SecurityContextHolder.createEmptyContext() 配合 setContext 的写法避免就地修改共享的上下文对象,与异步场景下的上下文隔离要求一致。认证过滤器与上下文存储的整体结构可参考 企业级项目实践指导手册 第 4.2 节。
刷新与续期策略
@Transactional(rollbackFor = Exception.class)
public TokenPair refresh(String refreshToken) {
RefreshTokenRecord record = refreshTokenMapper.selectByHash(sha256(refreshToken));
if (record == null || record.isUsed() || record.getExpireAt().isBefore(Instant.now())) {
if (record != null) {
// 已使用或已失效的刷新令牌再次出现:视为重放,撤销该用户全部刷新令牌
refreshTokenMapper.revokeAllByUserId(record.getUserId());
log.warn("refresh token replay detected, userId={}", record.getUserId());
}
throw new BizException("REFRESH_TOKEN_INVALID");
}
record.markUsed();
refreshTokenMapper.updateById(record);
return issueNewPair(record.getUserId()); // 轮换:同时签发新的刷新令牌
}
续期策略有两种取舍:固定窗口指刷新不延长刷新令牌的绝对有效期,用户在最长周期后必须重新登录;滑动窗口指每次刷新延长有效期,体验更好但凭据生命周期可能无限延续。涉及资金或敏感数据的系统通常采用固定窗口。
注销与强制下线
public void logout(String token, long userId) {
Claims claims = jwtService.parse(token);
long remainMillis = claims.getExpiration().getTime() - System.currentTimeMillis();
if (remainMillis > 0) {
// 黑名单键的 TTL 与令牌剩余有效期一致,避免键无界增长
stringRedisTemplate.opsForValue().set(
"prod:auth:jwt:blacklist:" + claims.getId(), "1", Duration.ofMillis(remainMillis));
}
revokeUserAllTokens(userId); // 递增令牌版本,使该用户全部已签发令牌立即失效
}
public void revokeUserAllTokens(long userId) {
stringRedisTemplate.opsForValue().increment("prod:auth:user:ver:" + userId);
}
令牌相关键的命名、TTL 与容量控制方式与缓存键设计同源,参见 Redis 缓存实践与常见问题 第 3.1 节。
高危:强制全部令牌失效(清空黑名单之外的令牌状态、批量递增全体用户的令牌版本、更换签名密钥)会使所有在线用户在同一时刻掉线,客户端需要重新登录,影响范围为全部活跃会话。执行前应确认业务是否允许集中重新登录,并避开业务高峰。回滚方式:令牌版本类操作应在变更前记录版本基准,误操作时可用备份的版本值恢复;若已递增且无法回退,只能等待客户端重新登录;密钥类操作需保留旧密钥与旧公钥,在观察窗口内可重新启用旧 kid 恢复已签发令牌的可用性。
多端登录与并发登录的控制
需要控制登录端数量时,可以按"用户加设备"维度记录会话,而不是只记录用户:
CREATE TABLE auth_session (
id BIGINT PRIMARY KEY,
user_id BIGINT NOT NULL,
jti VARCHAR(64) NOT NULL,
device_id VARCHAR(64) NOT NULL,
login_ip VARCHAR(64),
login_at DATETIME NOT NULL,
expire_at DATETIME NOT NULL,
revoked TINYINT NOT NULL DEFAULT 0,
UNIQUE KEY uk_jti (jti),
KEY idx_user_device (user_id, device_id)
);
策略上区分三种口径:同设备重复登录时使旧会话失效、限制同一用户的并发设备数(超出时按登录时间淘汰最早的会话)、敏感系统只允许单会话。无论采用哪种口径,注销与强制下线都应同时作用于会话表与令牌状态,只更新其中之一会出现"界面显示已下线但令牌仍可用"的不一致。
令牌在网关与微服务间的传递与校验位置
客户端 --Authorization: Bearer <token>--> 网关
网关:验签、校验 iss/aud/exp、校验版本号与黑名单
→ 剥离外部请求中的内部头(X-User-Id、X-Tenant-Id 等)
→ 注入受信任的内部头,转发到目标服务
→ 目标服务:读取内部头确定身份,并按接口与方法级注解校验权限
三点需要注意:
- 内部头必须由网关在校验后写入,同时剥离客户端传入的同名头,否则攻击者可以直接伪造身份头绕过认证;
- 服务不应无条件信任内部头,能够在服务内二次校验的场景(例如持有验签公钥)应做二次校验,尤其当服务端口可能被直接访问时;
- 网关到服务之间的链路需要额外的传输层保护或内部凭据,否则内部头的可信性依赖于网络隔离,而网络隔离不是应用层可控的保证。
3.3 授权落地
权限模型设计示例
CREATE TABLE sys_user (
id BIGINT PRIMARY KEY,
username VARCHAR(64) NOT NULL UNIQUE,
password_hash VARCHAR(100) NOT NULL,
dept_id BIGINT NOT NULL,
token_version INT NOT NULL DEFAULT 0,
status TINYINT NOT NULL DEFAULT 1
);
CREATE TABLE sys_role (
id BIGINT PRIMARY KEY,
code VARCHAR(64) NOT NULL UNIQUE, -- 如 ROLE_ADMIN
name VARCHAR(64) NOT NULL
);
CREATE TABLE sys_permission (
id BIGINT PRIMARY KEY,
code VARCHAR(128) NOT NULL UNIQUE, -- 如 order:read
type VARCHAR(16) NOT NULL, -- API / MENU / DATA
resource VARCHAR(255) NOT NULL -- 接口路径、菜单标识或数据维度
);
CREATE TABLE sys_user_role (
user_id BIGINT NOT NULL,
role_id BIGINT NOT NULL,
PRIMARY KEY (user_id, role_id)
);
CREATE TABLE sys_role_permission (
role_id BIGINT NOT NULL,
permission_id BIGINT NOT NULL,
PRIMARY KEY (role_id, permission_id)
);
CREATE TABLE sys_role_data_scope (
role_id BIGINT NOT NULL,
scope VARCHAR(32) NOT NULL, -- ALL / DEPT_AND_CHILD / DEPT / SELF
PRIMARY KEY (role_id)
);
模型上需要明确三点:权限按"操作加资源"命名而不是按菜单命名(菜单会变,操作语义相对稳定);数据范围属于角色属性而不是接口属性;用户状态与令牌版本存放在用户表,使停用与止损能作用于全部凭据。
数据级鉴权的实现方式
归属校验适用于"本人数据",查询条件中直接带上归属约束比查询后判断更安全,因为它从数据源上排除了越权结果:
public OrderDetail getOrderDetail(long orderId, long currentUserId) {
OrderDetail order = orderMapper.selectByIdAndOwner(orderId, currentUserId);
if (order == null) {
// 不存在与无权访问返回同一结果,避免通过错误信息枚举他人资源标识
throw new BizException("ORDER_NOT_FOUND");
}
return order;
}
数据范围过滤适用于"按组织层级可见"的场景,要点是过滤条件不可绕过,且必须覆盖列表、详情、导出、批量操作等全部入口:
@PreAuthorize("hasAuthority('order:read')")
public PageResult<OrderVO> page(OrderQuery query) {
DataScope scope = dataScopeService.currentScope(); // 按当前用户角色解析数据范围
query.setVisibleDeptIds(scope.getVisibleDeptIds()); // SELF 时收敛为本人
return orderMapper.page(query); // SQL 中强制拼接 dept_id IN (...)
}
<select id="page" resultType="OrderVO">
SELECT id, order_no, owner_id, dept_id, amount, status
FROM biz_order
WHERE 1 = 1
<if test="visibleDeptIds != null and visibleDeptIds.size() > 0">
AND dept_id IN
<foreach collection="visibleDeptIds" item="deptId" open="(" separator="," close=")">
#{deptId}
</foreach>
</if>
<if test="selfOnly == true">
AND owner_id = #{currentUserId}
</if>
</select>
写出路径同样需要校验,且不能只依赖读路径的校验:更新与删除语句应带归属或数据范围条件,并通过影响行数判断是否真正命中了允许范围内的数据。
权限变更的生效方式与缓存清理
@Transactional(rollbackFor = Exception.class)
public void grantRoles(long userId, List<Long> roleIds) {
userRoleMapper.deleteByUserId(userId);
roleIds.forEach(roleId -> userRoleMapper.insert(userId, roleId));
// 授权关系变更:事务提交后清理该用户的权限缓存并递增权限版本
afterCommit(() -> {
stringRedisTemplate.delete("prod:auth:perm:user:" + userId);
stringRedisTemplate.opsForValue().increment("prod:auth:perm:ver");
});
}
缓存清理需要覆盖全部变更入口(用户角色、角色权限、用户状态、部门调整),并在缓存键上设置短 TTL 作为兜底。若权限缓存的键只按角色维度组织,则用户维度的变更需要额外处理,否则会出现"角色权限已改但持有该角色的在线用户仍用旧权限"的现象。
3.4 密钥与配置实践
密钥的加载与配置结构
配置文件只声明来源与参数,不承载密钥内容:
security:
jwt:
issuer: https://auth.example.com
audience: order-service
key-source: ${JWT_KEY_SOURCE:kms} # 密钥来源:kms / vault / env
key-location: ${JWT_KEY_LOCATION} # 密钥在密钥服务中的路径或环境变量名
active-key-id: ${JWT_ACTIVE_KID} # 当前用于签发的密钥标识
access-token-ttl: 15m
refresh-token-ttl: 7d
clock-skew: 60s
启动时按 key-location 读取密钥并构建验签密钥集合(包含当前与上一版本),签发只使用 active-key-id 对应的私钥,验签按令牌头部的 kid 查找。密钥读取失败应导致启动失败,而不是退化为"无密钥运行"或默认密钥。
多环境隔离
开发、测试、生产使用相互独立的密钥与独立的授权服务器实例,配置通过 Profiles 隔离,具体加载优先级与激活方式见 Spring Boot Profiles 环境隔离 第四章;配置系统与自动装配的整体结构见 Spring Boot 第五章。隔离的目的不只是避免误连,还包括:生产密钥不落入开发环境,开发环境的令牌无法在生产环境通过校验。
密钥轮换流程
高危:密钥轮换涉及签发与验签两侧,操作不当会导致令牌校验失败或新旧令牌互不兼容。影响范围为使用该密钥的全部服务与全部已签发令牌。执行前需确认验签方已加载新公钥(非对称)或已同步新密钥(对称),并保留旧密钥直至最长的令牌有效期结束。回滚方式:配置中恢复 active-key-id 为原密钥标识,并确保原私钥仍在密钥服务中可用;若旧密钥已被删除且未备份,则已签发令牌无法恢复,只能要求客户端重新登录。
轮换按四个阶段执行,每个阶段之间保留观察窗口:
# 阶段一:生成新密钥对,写入密钥服务,同时保留旧密钥
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out jwt-2026-10.pem
openssl rsa -in jwt-2026-10.pem -pubout -out jwt-2026-10.pub.pem
# 阶段二:验签方加载新公钥(JWKS 端点同时提供新旧公钥),此时签发仍用旧密钥
curl -s https://auth.example.com/.well-known/jwks.json | jq '.keys[].kid'
# 阶段三:观察窗口内确认全部验签方均可解析新公钥后,切换签发密钥
# 配置 active-key-id 后灰度发布,观察令牌校验失败率与登录成功率
# 阶段四:旧令牌全部过期后,移除旧公钥,回收旧私钥
对称密钥的轮换缺少公私钥分离这一过渡手段,过渡期只能同时接受新旧两把密钥,因此需要在代码中显式支持密钥列表校验,否则轮换必然造成批量掉线。
密钥泄露后的更换步骤
- 确认泄露范围:泄露的是签名私钥、对称密钥、验签公钥还是密钥服务的访问凭据;确认泄露时长与可能的签发来源
- 生成新密钥并上线,使新密钥可用于签发
- 使基于旧密钥签发的令牌失效:由于旧密钥仍在验签集合中,需要同时从验签集合移除旧密钥,或递增全体用户的令牌版本
- 撤销全部刷新令牌,避免攻击者用已持有的刷新令牌换取新令牌
- 回溯访问日志,检查是否存在异常来源或异常权限的访问,必要时按安全事件流程取证
第 3 步与第 4 步的组合会造成全员重新登录,属于本文中影响面最大的操作之一,应在变更窗口内执行并提前通知。
3.5 接口安全加固清单
| 加固项 | 落地要点 | 常见遗漏 |
|---|---|---|
| 参数校验 | 请求对象使用声明式校验注解,服务层再做业务规则校验 | 只校验必填,不校验取值范围与集合元素个数上限 |
| 统一异常 | 业务异常映射为稳定错误码,系统异常统一兜底 | 响应中带出类名、SQL、堆栈与内部地址 |
| 限流 | 按接口与来源两个维度计数,登录与验证码接口单独收紧 | 只做全局限流,单个账号被暴力尝试时不受限 |
| 防重放 | 关键写接口使用幂等键或唯一约束,必要时叠加时间戳与随机数校验 | 只在网关做去重,绕过网关的入口无保护 |
| 敏感接口二次校验 | 改密、改绑、支付、导出、批量删除要求重新验证身份或二次认证 | 二次校验只做前端弹窗,后端未校验验证结果 |
| 错误信息最小化 | 认证失败与资源不存在返回统一信息,不区分"账号不存在"与"口令错误" | 通过错误信息差异枚举账号与资源标识 |
| 响应头与传输 | 强制 HTTPS,设置安全响应头,关闭不必要的方法与目录列表 | 内部调用使用明文,凭据在链路中可被截获 |
限流实现要点与降级方向(存储不可用时放行还是拒绝)参见 Redis 缓存实践与常见问题 第 2.3 节:
public boolean allow(String scene, String key, int limit, Duration window) {
String redisKey = "prod:ratelimit:" + scene + ":" + key;
Long count = stringRedisTemplate.opsForValue().increment(redisKey);
if (count != null && count == 1L) {
// 过期时间只在首次计数时设置,否则窗口会被反复重置
stringRedisTemplate.expire(redisKey, window);
}
return count == null || count <= limit; // 存储异常时的方向需显式定义,此处为放行
}
3.6 常见漏洞与修复对照
| 漏洞类型 | 错误写法 | 攻击方式 | 修复要点 |
|---|---|---|---|
| 水平越权 | orderMapper.selectById(id) 后直接返回 | 遍历或猜测资源标识读取他人数据 | 查询条件带归属约束;不存在与无权返回同一结果 |
| 垂直越权 | 管理接口仅靠前端隐藏入口 | 直接调用管理接口路径 | 服务端按权限判定;管理前缀配置独立规则并纳入测试用例,越权与鉴权类用例的覆盖方式见 Java 测试体系 |
| JWT 算法不校验 | 按头部 alg 选择验签算法 | 声明 none 或把非对称改为对称并用公钥验签 | 验签算法固定;未知 kid 直接失败;不提供算法回退 |
| JWT 声明不校验 | 只验签,不检查 iss、aud、exp | 使用其他系统签发的令牌访问 | 强制校验签发者、受众与有效期,容许有限时钟偏差 |
| 令牌泄露到日志 | 打印完整请求头或异常中的令牌 | 从日志系统获取令牌直接调用接口 | 日志脱敏;只记录 jti 或哈希前缀 |
| 令牌置于 URL | 通过查询参数传递令牌 | 令牌进入浏览器历史、代理日志与来源头 | 统一置于 Authorization 头 |
| 会话固定 | 登录成功后沿用原会话标识 | 预置会话标识诱导登录 | 认证成功后更换会话标识;登录接口不接受外部传入的标识 |
| CSRF | Cookie 会话下未校验来源与令牌 | 诱导浏览器发起状态变更请求 | 校验 CSRF 令牌、设置 SameSite、校验来源头 |
| XSS | 未转义输出与不安全富文本渲染 | 注入脚本窃取令牌或以用户身份操作 | 输出转义;富文本白名单;内容安全策略;令牌不置于脚本可读存储 |
| SQL 注入 | 字符串拼接查询条件与动态排序字段 | 构造条件绕过校验或读取全表 | 全量参数绑定;动态列名用白名单映射 |
| SSRF | 由参数决定服务端请求地址 | 指向内网服务或元数据地址 | 目标白名单、限制协议与端口、禁止访问内网地址、禁止跟随重定向 |
| 反序列化 | 接收不可信来源的原生序列化数据 | 利用 gadget 链在还原对象时执行代码 | 不使用不可信的原生序列化;替换为 JSON 等数据格式,见 序列化与反序列化 第 5.2 节 |
| 口令存储过弱 | MD5 加固定盐保存口令 | 获取哈希后离线破解 | 使用自适应哈希(BCrypt、Argon2);成本因子随硬件上调 |
| 密钥硬编码 | 签名密钥写入配置文件并提交仓库 | 获取密钥后自行签发任意身份令牌 | 密钥由环境变量或密钥服务提供;仓库与镜像中不出现密钥 |
| 接口枚举与暴力破解 | 登录失败信息区分账号是否存在,无尝试次数限制 | 批量尝试口令或枚举有效账号 | 统一错误信息与响应时间;按账号与来源双重限流;逐步加长冷却 |
3.7 排查与运维
认证失败与授权失败的区分与定位
两类问题的表现都在于请求被拒绝,但定位方向完全不同:
| 现象 | 状态码 | 常见成因 | 定位入手点 |
|---|---|---|---|
| 认证失败 | 401 | 未携带凭据、令牌过期、签名校验失败、iss 或 aud 不匹配、版本号不一致、命中黑名单 | 确认请求是否携带头部;解析令牌的 exp、iss、aud 与 kid;核对验签密钥集合与令牌版本 |
| 授权失败 | 403 | 权限未授予、权限缓存未更新、路径匹配未命中预期规则、数据范围为空 | 打印实际加载的 authorities 与所需权限表达式;核对权限缓存与角色关系;核对放行规则与注解表达式 |
定位时的两个常见误区:一是把 401 当作 403 处理,反复检查权限配置而实际问题在令牌校验;二是把 403 归因于前端未传参,实际是权限数据未加载。建议在认证过滤器与授权拒绝处理器中分别记录可关联的请求标识,使两类失败的链路可以区分。
令牌过期导致的批量掉线
批量掉线通常呈现为"某一时刻大量用户同时需要重新登录",成因有四类:
| 成因 | 判断依据 | 处理方向 |
|---|---|---|
| 集中签发导致同时过期 | 掉线时间点与上一次集中发布或集中续期时间吻合 | 签发时对有效期加入随机抖动,分散过期时刻 |
| 集群节点时钟漂移 | 部分节点校验失败而其他节点正常,与应用日志中的时间戳不一致 | 统一时间源并监控偏移量 |
| 令牌版本或黑名单键被整体清理 | 存储中出现键被清空或实例数据丢失的迹象 | 恢复存储;键的 TTL 与容量纳入监控 |
| 密钥轮换后旧密钥未保留 | 掉线时间点与密钥变更窗口吻合 | 恢复旧公钥,按 3.4 节的四阶段流程重新执行轮换 |
密钥更换后的兼容处理
密钥变更后的兼容问题集中在三处:验签方未及时加载新公钥、令牌头部缺少 kid 导致无法定位密钥、签发与验签的算法族不一致。处理原则是让验签集合先具备新密钥,再切换签发密钥,并在变更窗口内同时接受新旧 kid。缺少 kid 的历史令牌需要在过渡期按密钥逐个尝试验签,过渡期结束后此类令牌自然过期。
安全事件的取证与止损
1. 止损:撤销受影响的令牌与刷新令牌,必要时轮换密钥并停用相关账号
2. 控场:保留现场,避免在取证前清理日志、重启服务或覆盖容器文件系统
3. 取证:导出认证日志、接口访问日志、权限变更记录与网关访问记录,按同一时间线对齐
4. 定性:确定入口(凭据泄露、越权接口、第三方组件漏洞)、影响范围(涉及账号与数据)
5. 复盘:修补入口并补充检测手段,将本次事件的可疑特征加入监控规则
应用层的日志与线程栈、连接状态类证据的采集方式与诊断取舍见 应用诊断与调优 第二章与第 3.1 节;主机层的登录与提权排查方式见 Linux 主机加固与登录安全 第 5.11 节。
四、总结
- 接口暴露后的信任判定集中在三个问题上:谁在调用、能做什么、如何撤销;撤销能力由凭据形态决定,因此在选择认证方案时就需要一并考虑
- 服务端会话以状态换取即时撤销能力,无状态令牌以撤销能力换取扩展性与跨端一致性;两者可并存,但需明确各入口接受的凭据类型
- 会话固定通过认证成功后更换会话标识防护;无状态令牌的注销必须包含服务端动作,否则凭据在有效期内仍然可用
- JWT 的头部与载荷只做编码不做加密,载荷不应承载敏感信息;对称算法把签发能力扩散到全部持有密钥的组件,非对称算法可把签发收敛到授权服务器
- 无状态令牌的主动失效依赖黑名单、令牌版本号与短有效期三类补偿手段,单靠短有效期无法应对需要立即止损的场景
- OAuth2 是授权框架,OIDC 在其上补充身份层;授权码加 PKCE 是通用推荐方式,客户端凭证用于无用户上下文的服务间调用,密码模式与隐式模式已废弃
- 授权需要方法级、接口级、数据级三层同时成立;RBAC 用于功能级权限,数据权限用于行范围限定,ABAC 用于补充条件判定
- 权限缓存的失效需要覆盖用户角色、角色权限、用户状态与组织架构四类变更,删除与版本号叠加短 TTL 是较稳妥的组合
- Spring Security 由过滤器链完成请求级处理,认证结果存于线程局部上下文,异步与线程池场景需要显式传播;CSRF 是否关闭取决于凭据形态,CORS 允许携带凭据时来源不能为通配符
- 口令存储使用自适应哈希并保持成本因子更新;越权与重放是接口层最高频的问题,且无法由前端控制或令牌本身解决
- 签名密钥的生成、存储与轮换是认证体系的安全底座;密钥与凭据的应急处置遵循先止损再定位的顺序
- 登录、注销、令牌签发、授权变更与敏感操作都需要留痕并脱敏;留存期限与防篡改强度按合规要求与事件发现周期确定,应用层与主机层日志需要统一时间源以便关联
- 密钥轮换、强制全部令牌失效、关闭 CSRF 校验、放宽放行规则属于高危操作,执行前需确认影响范围、观察窗口与回滚方式,并在变更窗口内完成