4. 资源服务器配置：JWT令牌解析、权限校验、自定义鉴权异常处理

在异步导出服务中，资源服务器是OAuth2.0架构的最后一环，负责验证访问令牌的有效性、解析用户身份与权限，并最终决定是否放行请求。本章聚焦于Spring Security Resource Server的实战配置，涵盖JWT令牌解析、细粒度权限校验以及自定义鉴权异常处理三个核心模块。

4.1 JWT令牌解析与验证流程

资源服务器收到请求后，首先从 Authorization: Bearer <token> 头中提取JWT，然后执行以下验证链：

1. 签名验证：使用授权服务器提供的公钥（JWK Set URI或本地配置）验证JWT签名，防止令牌被篡改。
2. 有效期检查：校验 exp（过期时间）和 nbf（生效时间）声明，拒绝过期或未生效的令牌。
3. 颁发者校验：验证 iss 声明是否与授权服务器匹配。
4. 受众校验（可选）：验证 aud 声明是否包含当前资源服务器的标识。
5. 自定义声明校验：根据业务需求校验 scope、role 等自定义声明。

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://auth.example.com
          # 或直接指定 jwk-set-uri: https://auth.example.com/.well-known/jwks.json

以下SVG图展示了JWT令牌从请求到达资源服务器到完成解析的完整流程：

4.2 权限校验：从JWT声明到方法级控制

JWT令牌解析完成后，资源服务器需要根据令牌中的权限声明进行访问控制。Spring Security支持两种主流权限校验方式：

以下是一个自定义JWT权限转换器的实现示例：

@Component
public class CustomJwtAuthenticationConverter implements Converter<Jwt, AbstractAuthenticationToken> {

    @Override
    public AbstractAuthenticationToken convert(Jwt jwt) {
        // 从JWT中提取自定义roles声明
        List<String> roles = jwt.getClaimAsStringList("roles");
        if (roles == null) {
            roles = Collections.emptyList();
        }
        // 将roles转换为GrantedAuthority，并保留scope权限
        Set<GrantedAuthority> authorities = new HashSet<>();
        roles.forEach(role -> authorities.add(new SimpleGrantedAuthority("ROLE_" + role)));
        // 同时保留scope权限
        authorities.addAll(OAuth2TokenExtractor.extractAuthorities(jwt));
        return new JwtAuthenticationToken(jwt, authorities);
    }
}

在Security配置中注入该转换器：

@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http
        .oauth2ResourceServer(oauth2 -> oauth2
            .jwt(jwt -> jwt
                .jwtAuthenticationConverter(customJwtAuthenticationConverter())
            )
        )
        .authorizeHttpRequests(authz -> authz
            .antMatchers("/api/export/**").hasAuthority("SCOPE_export")
            .antMatchers("/api/admin/**").hasRole("ADMIN")
            .anyRequest().authenticated()
        );
    return http.build();
}

4.3 自定义鉴权异常处理

当JWT验证失败或权限不足时，Spring Security默认返回通用的401或403响应，缺乏业务可读性。通过自定义异常处理，可以返回结构化的错误信息，便于客户端定位问题。

以下SVG图展示了鉴权异常处理的分发路径：

实现自定义异常处理需要实现 AuthenticationEntryPoint（处理401未认证）和 AccessDeniedHandler（处理403无权限）：

@Component
public class CustomAuthenticationEntryPoint implements AuthenticationEntryPoint {

    @Override
    public void commence(HttpServletRequest request, HttpServletResponse response,
                         AuthenticationException authException) throws IOException {
        response.setContentType("application/json;charset=UTF-8");
        response.setStatus(HttpStatus.UNAUTHORIZED.value());

        Map<String, Object> errorBody = new HashMap<>();
        errorBody.put("code", 401);
        errorBody.put("message", "认证失败：" + authException.getMessage());
        errorBody.put("path", request.getRequestURI());
        errorBody.put("timestamp", LocalDateTime.now().toString());

        response.getWriter().write(new ObjectMapper().writeValueAsString(errorBody));
    }
}

@Component
public class CustomAccessDeniedHandler implements AccessDeniedHandler {

    @Override
    public void handle(HttpServletRequest request, HttpServletResponse response,
                       AccessDeniedException accessDeniedException) throws IOException {
        response.setContentType("application/json;charset=UTF-8");
        response.setStatus(HttpStatus.FORBIDDEN.value());

        Map<String, Object> errorBody = new HashMap<>();
        errorBody.put("code", 403);
        errorBody.put("message", "权限不足：" + accessDeniedException.getMessage());
        errorBody.put("path", request.getRequestURI());
        errorBody.put("timestamp", LocalDateTime.now().toString());

        response.getWriter().write(new ObjectMapper().writeValueAsString(errorBody));
    }
}

在Security配置中注册这两个处理器：

@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http
        .exceptionHandling(exceptions -> exceptions
            .authenticationEntryPoint(customAuthenticationEntryPoint)
            .accessDeniedHandler(customAccessDeniedHandler)
        )
        .oauth2ResourceServer(oauth2 -> oauth2
            .jwt(jwt -> jwt
                .jwtAuthenticationConverter(customJwtAuthenticationConverter())
            )
        )
        .authorizeHttpRequests(authz -> authz
            .antMatchers("/api/export/**").hasAuthority("SCOPE_export")
            .anyRequest().authenticated()
        );
    return http.build();
}

4.4 常见问题与避坑指南