线上最烦的一类 Spring Security 问题，是前端说“我明明带了 JWT，接口还是 401”，后端日志里又夹着 403、/error、AccessDeniedException。很多时候不是 token 真坏了，而是过滤链、资源服务器配置、权限前缀和异常入口混在一起看，越查越乱。
这篇按我排查生产事故的顺序写，不照搬 Spring Security 官方文档。官方文档用于核对 Resource Server、Bearer Token、JWT 和授权机制，真正落地时我们要把 401/403、SecurityFilterChain 顺序、SecurityContext 和 /error 二次拦截拆开看。
先把 401 和 403 分清楚
401 是认证没过：没有 token、Bearer 头格式不对、JWT 过期、签名不对、issuer 或 audience 校验失败。403 是认证已经过了，但权限不够：Authentication 进了 SecurityContext，可它没有接口要求的 authority。
我排查时会先看响应头和日志：如果是 Bearer token invalid_token，优先查 JwtDecoder；如果 Authentication 已经存在，再看 hasRole、hasAuthority、scope 前缀和方法级权限。
过滤链顺序比你想的更重要
项目里常有多条 SecurityFilterChain，比如管理后台、开放 API、内部回调各一条。matcher 顺序写错，请求可能命中另一条链。看起来是 JWT 失败，实际是压根没走你以为的那条配置。
@Bean
SecurityFilterChain api(HttpSecurity http) throws Exception {
return http
.securityMatcher("/api/**")
.authorizeHttpRequests(auth -> auth
.requestMatchers("/error").permitAll()
.requestMatchers("/api/admin/**").hasAuthority("SCOPE_admin")
.anyRequest().authenticated())
.oauth2ResourceServer(oauth -> oauth.jwt())
.build();
}
scope 和 role 前缀是高发坑
JWT 里常见的是 scope 或 scp，Spring Resource Server 默认会映射成 SCOPE_xxx。于是 token 里是 admin，代码却写 hasRole("ADMIN")，最后认证成功但授权失败。这个坑本质不是 JWT，而是权限命名没统一。
我的建议是：接口层统一用 hasAuthority("SCOPE_xxx")，或者显式配置 JwtAuthenticationConverter，把团队里的权限模型转成一致的 GrantedAuthority。不要一部分接口写 ROLE_，另一部分写 SCOPE_。
/error 二次拦截会制造假象
有时业务代码抛异常，Spring Boot 转发到 /error，但 /error 没放行，又被 Spring Security 拦了一次。最后你看到的是 401 或 403，却不是最初的业务异常。生产里我会给 /error、健康检查、静态资源这类入口明确白名单，同时保留业务异常日志。
上线检查清单
- 每条 SecurityFilterChain 的 matcher 是否互斥，顺序是否符合预期？
- JWT 的 issuer、audience、过期时间和签名 key 是否和环境一致？
- 接口使用 hasRole 还是 hasAuthority，是否和 token claim 映射一致？
- /error、actuator health、公开回调是否明确 permitAll？
- 是否有集成测试覆盖无 token、过期 token、权限不足和正常访问？
- 认证失败和授权失败是否分别打出可排查的日志字段？
最后聊两句
Spring Security 的复杂不是坏事，它只是把认证、授权、异常处理都拆得很细。真正出事故时，最怕把这些概念搅成一团。
我的经验是：先问“有没有 Authentication”，再问“有没有需要的 authority”。这两个问题一分开，JWT 401/403 的大多数坑都会变得很直。
