Skip to content

Spring Security 7 + OAuth2.1 认证授权体系:从配置写法到数据级权限 ​

1. 学完这一节,你应该能…… ​

  • 能从一次 401 或 403 的响应头,倒推出是哪一层拒绝了你,而不是先去改 SecurityFilterChain
  • 能默写出 Spring Security 7 里唯一的 DSL 形态,并说清 and() 为什么被删掉
  • 会判断一段鉴权逻辑该放在网关、URL 规则、方法注解还是业务代码里
  • 能对着 exp、aud、typ 三个声明,讲清资源服务器到底校验了什么、漏了什么

这一节假定你写过两年 Java 后端,用过至少一次 @PreAuthorize。没写过也不要紧,但 @Configuration 和 Bean 的含义我不再解释。

2. 这节课在整个类目里的坐标 ​

认证回答"你是谁",授权回答"你能干什么",中间靠一枚令牌把结论运过去。三者不是三个模块,是一条链上的三段。

图里最左侧那段今天基本没有争议,争议全部集中在右侧两段该切多细。这也是初学者最常失衡的地方:把配置写得很漂亮,授权却还停在"登录了就能用"。

3. 一个封号要等六小时的下午 ​

2026 年 3 月,一家做 B 端订单的公司把 access token 有效期从 30 分钟改成 8 小时。原因很朴素:客户经理下午接个电话回来就要重新登录,一周积了四十多张投诉单。

改动上线两周后,风控发现一个账号在异地登录,按流程封停。结果这个账号又正常下了六小时的单。

排查没有任何悬念:封停只改了业务库里的用户状态,而资源服务器从头到尾不查库。它信的是一张签名有效、尚未过期的票据。票据本身没有"作废"这个字段。

所以这一节真正要回答的问题只有一个:一枚已经发出去的令牌,凭什么能被叫回来?如果叫不回来,你愿意为它等多久?

4. 四个角色、两套词汇、一个前缀 ​

OAuth 2.1 的角色划分看着啰嗦,但每一处混淆最后都会变成一个权限漏洞。

角色是谁初学者常犯的错
资源所有者 Resource Owner用户本人把它和"客户端"当成一回事
客户端 Client你的前端或后台服务把 client_secret 塞进浏览器 JS
授权服务器 Authorization Server签发令牌的一方以为它等同于"用户中心"
资源服务器 Resource Server验令牌的一方,通常就是你的业务服务以为验签通过就等于有权访问

第二行那个错值得展开,它是本节第一个反例。有人在 React 里直接拿 client_id + client_secret 去 /token 换令牌,理由是这样"省一次跳转"。这等于把客户端身份公开写在源码里——任何打开 DevTools 的人都能冒充你的应用去申请令牌。公共客户端(SPA、移动端、桌面端)的正确做法是授权码 + PKCE,密钥永远不下发到端上。

第二套词汇是 scope 与 authority。前者是协议概念,表示授权服务器授予这个客户端的权限范围,写在 JWT 的 scope 声明里;后者是 Spring 的内部概念,是 Authentication 上挂的权限字符串。Spring 把 scope 的每个值映射成一条 authority,并统一加 SCOPE_ 前缀。

这里容易卡住

hasRole("ADMIN") 会自动补成 ROLE_ADMIN,hasAuthority("ADMIN") 不会补任何东西。而 JWT 的 scope 映射出来是 SCOPE_order:admin。三种前缀(无前缀、ROLE_、SCOPE_)混用,表现是"配置肉眼看着全对,接口就是 403",且日志里只有一行 Access Denied。

5. 把认证链路写成一份能跑的配置 ​

Spring Security 7 只保留 lambda DSL 一种写法。判断一份配置的年代有个土办法:出现 and() 是 5.x 风格,出现 authorizeRequests() 是 6.0 之前,两者都不出现才是 7。

java
// Spring Security 7.1.x + Boot 4.0.x,无状态资源服务器
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
public class ApiSecurityConfig {

    @Bean
    SecurityFilterChain apiChain(HttpSecurity http) throws Exception {
        http
            .securityMatcher("/api/**")
            .csrf(csrf -> csrf.disable())          // 只在没有 Cookie 会话时成立
            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/public/**").permitAll()
                .requestMatchers("/api/admin/**").hasAuthority("SCOPE_order:admin")
                .anyRequest().authenticated())
            .oauth2ResourceServer(o -> o.jwt(Customizer.withDefaults()));
        return http.build();
    }
}
yaml
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://idp.example.com/issuer

issuer-uri 的作用不只是校验 iss,它还会触发一次发现请求,把 JWK Set 地址拉回来。启动后按下面三条命令验收,预期输出写在注释里:

bash
# 无令牌:预期 401,且响应头 WWW-Authenticate 以 Bearer 开头
curl -s -i http://localhost:8080/api/orders | head -2

# 有效令牌:预期 200
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/orders

# scope 不足:预期 403(不是 401,区别在于身份已认证但无权限)
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $USER_TOKEN" http://localhost:8080/api/admin/orders

401 和 403 的分界必须刻在脑子里:401 是"我没认出你",403 是"我认出你了,但你不能干这个"。把 403 当 401 去排查,会让你在错误的方向上改一小时配置。

这份配置有个缺口,默认校验器不查 aud。一个授权服务器同时给订单域和用户域签令牌时,给用户域签的那张,签名、iss、exp 全部合规,照样能调订单接口。补法是往解码器上叠一层:

java
// Spring Security 7.1.x:在默认校验器上叠加 audience 校验
@Bean
JwtDecoder jwtDecoder(@Value("${spring.security.oauth2.resourceserver.jwt.issuer-uri}") String issuer) {
    NimbusJwtDecoder decoder = NimbusJwtDecoder.withIssuerLocation(issuer).build();
    OAuth2TokenValidator<Jwt> withAudience =
            new JwtClaimValidator<List<String>>("aud", aud -> aud != null && aud.contains("order-api"));
    decoder.setJwtValidator(new DelegatingOAuth2TokenValidator<>(
            JwtValidators.createDefaultWithIssuer(issuer), withAudience));
    return decoder;
}

预期结果:拿一张 aud 只含 user-api 的令牌请求订单接口,返回 401 与 error="invalid_token",而不是 200 也不是 403。这个差异很重要——401 说明你在校验层就拒了,403 说明校验通过、被 URL 规则拒了,两者对应完全不同的后续排查路径。

6. 授权要能收到数据那一行 ​

把 URL 规则写长很容易,收细很难。实际可用的分层是四层,每层都只解决自己那一层的问题:

层次手段拦得住拦不住
网关路由级 scope 校验完全没权限的调用越权的资源 ID
URL 规则requestMatchers().hasAuthority()按路径粗粒度隔离同路径下的对象差异
方法级@PreAuthorize按操作细粒度控制数据归属
领域层业务代码里的归属判断对象级越权无
java
@Configuration
@EnableMethodSecurity            // 7.x 仍然只需这一个注解,prePostEnabled 默认开启
public class MethodSecurityConfig { }

@Service
public class OrderAdminService {

    @PreAuthorize("hasAuthority('SCOPE_order:read')")
    public OrderBrief query(String orderNo) { ... }

    @PreAuthorize("hasAuthority('SCOPE_order:write')")
    public void cancel(String orderNo, String ownerId, String currentUser) {
        repository.markCancelled(orderNo, ownerId, currentUser); // 归属校验在业务层做
    }
}

请注意 cancel 的归属判断我故意挪进了 Service,而原始示例是写成 #ownerId == authentication.name 的。这里给一个明确判断:不建议把数据归属判断塞进 SpEL。理由不是语法难写,而是这类判断一旦涉及"这单是不是我的组长的""这个客户有没有代理关系",就得跨表查库,最后你会得到一个在注解里写业务逻辑、既不能单测也没有事务边界的怪物。

scope 只回答"能不能调这个接口",永远不回答"能不能动这一条数据"。把两件事混在一起,是权限设计里最贵的误解。

7. 三条几乎人人都信错的判断 ​

第一,很多人以为 csrf().disable() 是无状态服务的标配,实际上它只在你完全不使用 Cookie 会话时成立。一旦网关做了 session 共享、或者前端有 SameSite=Lax 的登录态 Cookie,关掉 CSRF 就等于把写接口暴露给跨站表单。

第二,很多人以为 @PreAuthorize 标在 Service 方法上就必然生效,实际上同类内部调用(this.cancel(...))绕过代理,注解形同注释。判断办法是看调用是否从 Bean 外部进来,而不是看注解写没写。

第三,很多人以为 JWT 的 typ 头由 Nimbus 在解析阶段检查。7 里的实际组合是:JwtValidators.createDefaultWithIssuer 自动挂上 JwtTypeValidator,而 NimbusJwtDecoder 的 validateTypes 默认为 false——检查由 Spring 的校验器完成。如果你在 6.5 升级准备阶段手写过 validateTypes(false) 加 JwtTypeValidator.jwt(),那段代码现在可以整段删掉。

还有一处细节,只有被它拖过一次的人才会记住:NimbusJwtDecoder 内部拉 JWK Set 用的默认 RestOperations,连接与读取超时是 30 秒(6.5 时代是 500 毫秒)。这个数字我没有在升级环境里逐版本对照过,属于官方迁移说明里的说法,未核实。但它造成的现象很明确——授权服务器不可达时,首个请求会阻塞很久,网关侧超时反而先触发,日志上看像是"网关超时",实际是资源服务器在等 JWK。要恢复快速失败,得自己传一个配好超时的 RestOperations。

8. 令牌失效:三条路和它们各自的账单 ​

方案生效延迟每请求开销额外依赖适用
短 AT(5–15 分钟)+ refresh 轮换最长等于 AT 有效期无无绝大多数业务系统
吊销列表 / token 版本号秒级一次缓存查询Redis有"立刻踢人"要求
opaque token + introspection实时一次内省调用授权服务器可用性强合规场景

默认答案是第一行。refresh token 一次性使用并轮换,服务端记录家族(family id + 已轮换次数 + 绝对过期时间),一旦出现旧令牌被重复使用,就判定泄露并吊销整条家族。这套机制不依赖共享存储也能挡住大部分重放。

这张状态机里没有"用户点登出就全局失效"这条边,这是刻意画掉的。想做到它,只能落到吊销列表或版本号上,那已经是有状态方案。

第二层的取舍很具体:把 token_version 放进 JWT 声明,资源服务器用本地缓存(Caffeine,TTL 30 秒)比对。缓存 TTL 就是吊销延迟的下界。不建议把 TTL 设成 0 或 1 秒——那等于每请求查一次库,无状态带来的横向扩展优势没了,却还留着 JWT 的复杂度,不如直接用 opaque token。

9. 三道留给你的题 ​

一,你的服务补上 aud 校验了吗?一个授权服务器同时给订单域和用户域签令牌,如果两个资源服务器都不校验 audience,一张用户域的令牌能拿去调订单接口吗?请画出请求会经过哪几层。

二,假设合规要求"封号 30 秒内生效",你会把版本号存在哪里、TTL 定多少、Redis 挂掉时的行为是什么?把三种失败模式写下来。

三,某天线上出现"部分接口 403、部分正常"。请给出一条按顺序执行的排查路径,并说明每一步你会看哪个日志字段。

10. 八组词,一句话一个 ​

这八个词在本节里反复出现,混淆任意一对都会变成一次 403。

术语英文一句话解释
资源所有者Resource Owner有权授予访问权限的实体,通常就是用户
公共客户端Public Client无法安全保存密钥的客户端,SPA、App、桌面程序
PKCEProof Key for Code Exchange用一次性的 verifier/challenge 绑定授权码,防拦截重放
访问令牌Access Token短期凭证,本节的 JWT 就是它的载体形式
权限范围Scope授权服务器授予客户端的权限集合,映射后带 SCOPE_ 前缀
受众Audience(aud)令牌的预期接收方,默认不校验,必须自己加
内省Introspection资源服务器向授权服务器实时询问令牌状态
令牌家族Token Family一次授权派生的整条 refresh 链,用于整体吊销

官网的迁移指南和 OAuth 2.1 草案(截至 2026 年 11 月仍是 draft-ietf-oauth-v2-1-17)值得各读一遍,后者里"PKCE 强制、删除隐式与密码模式、重定向 URI 精确匹配"这几条,已经被 RFC 9700 写成"应当"。

把草案当事实标准用是可以的,但要清楚它还不是 RFC。这也是为什么很多团队的合规评审至今只认 RFC 9700 而不认 2.1。