1 / 4概念
Middleware
Spring Security 把认证与授权写成一条有序的 filter chain,Actuator 与 Micrometer 把进程状态变成可采集的信号。两件事都在业务代码之外,所以判断标准是能否说清一个请求在链的哪一环被拦下,以及一次滚动更新为什么没有丢请求。
1 概念
1.1 一句话定义
Spring Security 是一组按固定顺序排列的 servlet filter,每个 filter 只回答放行、改写还是终止。认证建立 Authentication 并放进 SecurityContext,授权按路径或方法决定是否放行,Actuator 把进程内状态暴露成端点。
1.2 它解决什么问题
- 横切关注点外移:认证与授权不写进业务方法,规则可集中审阅。
- 凭据集中处理:散列、令牌解析与会话管理只有一处实现。
- 策略可组合:路径级与方法级规则可以叠加,也能按路径拆成多条链。
- 状态可采集:健康、指标、配置与线程转储有标准出口。
- 发布可控:探针与优雅停机让滚动更新不丢在途请求。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
| bean 的创建、条件评估与配置绑定 | Container and Configuration |
| 参数绑定、校验与错误映射 | Web and Data |
| OAuth2、OIDC 与密码学原语 | Authentication & Authorization |
| XSS、SQL 注入与 CSRF 攻击面 | Web Security |
| 堆、GC 与线程模型 | JVM Runtime |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
SecurityFilterChain | 一条有序的过滤器链 | 不是单个 filter |
Authentication | 已认证主体及其权限 | 不是会话 |
SecurityContext | 当前请求的安全上下文 | 默认请求级 |
AuthenticationManager | 认证入口,委派给 provider | 不做授权判断 |
AuthenticationProvider | 具体认证逻辑 | 与 UserDetailsService 分工不同 |
UserDetailsService | 按用户名取凭据 | 只负责加载 |
PasswordEncoder | 密码散列与校验 | 不是加密,也不可逆 |
GrantedAuthority | 权限字符串 | 不是角色,需加前缀 |
SecurityContextHolder | 上下文存取策略 | 线程绑定,需显式传播 |
| 探针 | 存活与就绪信号 | liveness 触发重启,readiness 只摘流 |
| 管理上下文 | 管理端点的端口与路径 | 可以与业务端口分离 |
2 机制
2.1 心智模型
一条请求先过 filter chain,再过 MVC。链上每个 filter 都有固定位置,位置错了是安全缺陷而不是样式问题。运行侧则是一条时间线:启动、就绪、服务、摘流、关闭,探针与停机配置决定这条线是否平滑。
2.2 机制拆解
- 链的顺序:
SecurityContextHolderFilter建立上下文,CorsFilter处理预检,CsrfFilter校验令牌,认证 filter 建立Authentication,ExceptionTranslationFilter翻译安全异常,AuthorizationFilter最后决策。 - 认证路径:
AuthenticationManager按Authentication的类型选 provider,provider 用UserDetailsService取凭据并用PasswordEncoder比对,成功后写进SecurityContextHolder。 - 会话与令牌:表单登录把身份存进
HttpSession,服务端可立即注销;无状态资源服务器每次从Authorization头解析 JWT,水平扩展简单,但注销只能靠短有效期。 - 方法安全:
@EnableMethodSecurity为标注@PreAuthorize的 bean 生成代理,判断发生在方法调用之前,自调用同样绕过代理。 - 端点暴露:Actuator 端点是 bean 加 MVC 映射,
exposure.include决定哪些可访问,management.server.port可以把它们挪到另一个端口。 - 指标:Micrometer 提供门面,注册表把计数器、计时器与分布摘要导出到 Prometheus 或 OTLP 后端。
- 探针:
liveness与readiness是两组独立的HealthIndicator,前者应只包含进程自身,后者可包含数据库与下游。 - 优雅停机:
server.shutdown=graceful让容器停止接收新请求,等在途请求结束后再关线程池,宽限期由生命周期超时限定。
2.3 完整枚举
Spring Security 为无状态 API 组装出的 filter chain 完整顺序:
| 顺序 | filter | 作用 |
|---|---|---|
| 1 | DisableEncodeUrlFilter | 禁止把会话 id 编进 URL |
| 2 | WebAsyncManagerIntegrationFilter | 把上下文传入异步请求 |
| 3 | SecurityContextHolderFilter | 建立并清理上下文 |
| 4 | HeaderWriterFilter | 写安全响应头 |
| 5 | CorsFilter | 处理跨域与预检 |
| 6 | CsrfFilter | 校验 CSRF 令牌 |
| 7 | LogoutFilter | 处理注销 |
| 8 | BearerTokenAuthenticationFilter | 解析 bearer 令牌 |
| 9 | RequestCacheAwareFilter | 恢复被拦截前的请求 |
| 10 | SecurityContextHolderAwareRequestFilter | 把上下文适配到 servlet 请求 |
| 11 | AnonymousAuthenticationFilter | 填充匿名身份 |
| 12 | ExceptionTranslationFilter | 翻译认证与授权异常 |
| 13 | AuthorizationFilter | 做授权决策 |
2.4 关键数字与量级
| 指标 | 量级 | 说明 |
|---|---|---|
| filter 链长度 | 十余个 | 随配置增减 |
| bcrypt 成本 | 10 轮 | 单次数十毫秒,决定登录接口吞吐 |
| 访问令牌有效期 | 5–60 分钟 | 越长注销越难 |
| 健康检查间隔 | 5–10 秒 | 由编排决定 |
| 优雅停机宽限 | 20–30 秒 | 应小于编排的终止宽限期 |
| 指标暴露开销 | 与标签基数相关 | 高基数标签会拖垮注册表 |
3 实践
3.1 最小示例
@Configuration
@EnableWebSecurity
class SecurityConfig {
@Bean
SecurityFilterChain api(HttpSecurity http) throws Exception {
return http
.securityMatcher("/api/**")
.csrf(csrf -> csrf.disable())
.sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
.authorizeHttpRequests(auth -> auth
.requestMatchers("/api/public/**").permitAll()
.requestMatchers(HttpMethod.GET, "/api/orders/**").hasAuthority("SCOPE_orders:read")
.anyRequest().authenticated())
.oauth2ResourceServer(o -> o.jwt(Customizer.withDefaults()))
.build();
}
@Bean
PasswordEncoder passwordEncoder() {
return new BCryptPasswordEncoder();
}
}
追踪:GET /api/orders/42 先过容器里的 springSecurityFilterChain,SecurityContextHolderFilter 建立空上下文,BearerTokenAuthenticationFilter 从 Authorization 头取出 JWT 交给 AuthenticationManager,解析成功后得到带 SCOPE_orders:read 的 Authentication;AuthorizationFilter 命中第二条规则,请求才进入 DispatcherServlet。
失败路径由 ExceptionTranslationFilter 决定:未认证抛 AuthenticationException,由 AuthenticationEntryPoint 转成 401;已认证但缺权限抛 AccessDeniedException,由 AccessDeniedHandler 转成 403。运维侧补三项属性即可:端点白名单 health,info,prometheus、server.shutdown=graceful、生命周期超时 20 秒。
3.2 常用操作与参数
| 操作 | 写法 | 说明 |
|---|---|---|
| 定义链条 | SecurityFilterChain 加 securityMatcher | 按路径划分多条链 |
| 无状态 API | SessionCreationPolicy.STATELESS | 配合资源服务器 |
| 密码散列 | BCryptPasswordEncoder | 强度按 CPU 预算选 |
| 取用户 | UserDetailsService | 也可直接接 IdP |
| 方法级授权 | @EnableMethodSecurity 加 @PreAuthorize | 生成代理 |
| 跨域 | CorsConfigurationSource | 预检必须放行 |
| 关闭 CSRF | csrf.disable() | 只对无 cookie 的 API |
| 暴露端点 | management.endpoints.web.exposure.include | 白名单,不用通配 |
| 分离端口 | management.server.port | 管理端点走内网 |
| 打开探针 | management.endpoint.health.probes.enabled | 编排平台需要 |
| 优雅停机 | server.shutdown=graceful | 配合生命周期超时 |
3.3 标准流程
- 先定会话模型,再写 filter chain。
- 每条链用
securityMatcher限定路径,不要一条链管全部。 - 具体规则在前,
anyRequest兜底在后。 - 密码只存散列,强度与登录吞吐一起评估。
- 方法级授权放在 service,不放 controller。
- 端点只开 health、info 与指标,其余走内网或关闭。
- 优雅停机宽限期小于编排的终止宽限期。
- 日志带 trace id,认证失败要能追溯到主体。
3.4 与相邻技术的组合
- Container and Configuration:filter chain 也是 bean,多条链之间的顺序由
@Order决定。 - Web and Data:链先于
DispatcherServlet,异常翻译发生在 MVC 之外。 - Authentication & Authorization:协议与凭据格式的细节归那一页。
- Web Security:链的位置决定攻击面,输入校验不能替代授权。
- 编排与指标后端:探针语义与指标格式要跟平台对齐。
3.5 选型维度
| 维度 | 取值 | 影响 |
|---|---|---|
| 会话模型 | session / 无状态令牌 | 横向扩展与注销能力 |
| 认证方式 | 表单 / JWT 资源服务器 / mTLS | 客户端类型与实现量 |
| 授权粒度 | 路径级 / 方法级 / 两者 | 表达式复杂度与代理开销 |
| 密码算法 | bcrypt / argon2 | CPU 成本与参数调优 |
| 端点暴露 | 关闭 / health / 全量 | 泄露面与运维便利 |
| 停机方式 | 立即 / 优雅 | 5xx 比例与重试压力 |
3.6 决策规则
- API 用无状态令牌;浏览器会话保留 CSRF。
- 授权规则必须有
anyRequest兜底,不要依赖默认放行。 - 白名单只到路径级,不要按角色散开。
- 管理端点与业务端口分离,或整体只在内网可达。
- liveness 只反映进程,readiness 才反映依赖。
- 停机宽限期留足在途请求,同时小于编排的宽限。
3.7 替代方案对比
| 方案 | 优势 | 代价 | 适用 |
|---|---|---|---|
| Spring Security | 组件完整、可组合 | 配置复杂、调试成本高 | 通用服务 |
| 自写 filter | 简单可读 | 边界情况要自己补 | 单点内部服务 |
| 网关集中认证 | 客户端简单 | 单点故障与额外延迟 | 多服务统一入口 |
| Apache Shiro | 概念少、上手快 | 生态较弱 | 遗留系统 |
| 外部 IdP 托管 | 免自建、易合规 | 外部依赖与费用 | SaaS 集成 |
3.8 何时不该用
- 纯静态站点,没有服务端会话与授权。
- 一次性脚本或内部工具,不需要散列与端点。
- 没有编排平台时,优雅停机没有对手方配合,收益有限。
- 不要把授权写成注解堆叠,规则该集中到一处。
- 不要用健康检查做业务监控,它会拖慢探针并放大误报。
4 边界
4.1 典型故障
| 症状 | 根因 | 处理 |
|---|---|---|
| 登录成功但仍 403 | 权限前缀不匹配 | 看 Authentication#getAuthorities |
| 一直 401 | 令牌解析失败或资源服务器未配 | 开启 security 调试日志 |
| 预检请求 401 | 预检未被放行 | 让 CorsFilter 前置放行 OPTIONS |
| 无状态 API 报 CSRF 403 | 没关 CSRF | 关闭 CSRF 或改回会话 |
@PreAuthorize 不生效 | 未开方法安全,或自调用 | 检查代理与注解 |
| 端点 404 | 未加入 exposure.include | 显式开放 |
| 端点 401 | 业务链拦住了管理路径 | 单独建管理链 |
| 启动即未就绪 | readiness 依赖超时 | 调整分组或超时 |
| 停机时出现 502 | 立即关闭 | 开优雅停机 |
| 日志没有 trace id | 上下文未传播 | 补过滤器或网关透传 |
4.2 反模式
| 做法 | 后果 | 替代 |
|---|---|---|
| 管理端点全开 | 配置、堆栈与环境信息外泄 | 白名单加认证 |
| 明文或可逆存储密码 | 泄露即全损 | 散列 |
permitAll 兜底 | 新接口默认放行 | anyRequest 认证 |
| 一条链管所有路径 | 规则互相干扰 | 按 securityMatcher 拆分 |
| 健康检查返回依赖细节 | 信息泄露 | 只返回概要状态 |
| 关掉 CSRF 又用 cookie 会话 | 跨站请求伪造 | 保留 CSRF |
4.3 可观测信号
认证失败率、401 与 403 的比例、按路径的 filter 耗时、http.server.requests 的状态维度、探针状态变化与重启次数、堆使用量、活跃线程数与池饱和、散列耗时、停机期间的在途请求数。
4.4 安全 / 性能 / 一致性边界
- 安全边界:认证与授权不替代输入校验与参数化查询,链通过不等于请求安全。
- 顺序边界:filter 顺序是契约,重排会让 CORS 或 CSRF 失效。
- 运维边界:liveness 失败会重启,readiness 失败只摘流量,两者不能混用。
- 性能边界:散列与探针都是额外成本,探针频率过高会变成一种负载。