Spring Security 6 OAuth2ResourceServer无法获取UserDetails问题排查

在Spring Boot 3 + Spring Security 6的OAuth2资源服务器模式下，你遇到的@AuthenticationPrincipal无法获取CustomUserDetails的核心原因是：资源服务器默认的认证流程不会自动调用UserDetailsService加载用户信息。默认情况下，资源服务器验证JWT有效性后，会创建JwtAuthenticationToken，其principal是Jwt对象而非UserDetails，因此直接注入CustomUserDetails会返回null。

解决步骤 #

1. 修改自定义JWT认证转换器，整合UserDetailsService

需要在你的customAuthenticationConverter()中，手动调用CustomUserDetailsService加载用户信息，并将CustomUserDetails作为认证主体返回。这样SecurityContext中的Authentication就会携带CustomUserDetails实例。

示例代码：

@Bean
public JwtAuthenticationConverter customAuthenticationConverter(CustomUserDetailsService userDetailsService) {
    // 保留你原有的权限转换逻辑（如果有）
    JwtGrantedAuthoritiesConverter authoritiesConverter = new JwtGrantedAuthoritiesConverter();
    // 可根据需求配置权限前缀、提取字段等，比如：
    // authoritiesConverter.setAuthorityPrefix("ROLE_");
    // authoritiesConverter.setAuthoritiesClaimName("roles");

    JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
    converter.setJwtGrantedAuthoritiesConverter(jwt -> {
        // 1. 从JWT中提取用户唯一标识（需与你的UserRepository查询字段匹配，这里假设是sub字段）
        String userId = jwt.getClaim("sub");
        // 2. 调用UserDetailsService加载用户信息
        CustomUserDetails userDetails = userDetailsService.loadUserByUsername(userId);
        // 3. 合并JWT自带权限与数据库中用户权限（按需选择，也可只保留数据库权限）
        Set<GrantedAuthority> mergedAuthorities = new HashSet<>(authoritiesConverter.convert(jwt));
        mergedAuthorities.addAll(userDetails.getAuthorities());
        // 4. 返回包含CustomUserDetails的Authentication对象
        return new UsernamePasswordAuthenticationToken(userDetails, jwt, mergedAuthorities);
    });
    return converter;
}

2. 确保SecurityFilterChain配置正确

你的现有SecurityFilterChain中已经引用了customAuthenticationConverter()，无需额外修改，但注意：.userDetailsService(userDetailsService)在资源服务器模式下不会自动触发，核心逻辑还是靠转换器中的手动调用。

3. 验证接口注入

修改后的接口可以直接通过@AuthenticationPrincipal获取CustomUserDetails：

@GetMapping("/api/admin/you")
public String showProfile(@AuthenticationPrincipal CustomUserDetails userDetails) {
    return "Details: 用户ID=" + userDetails.getUsername() + ", 状态=" + (userDetails.isEnabled() ? "启用" : "禁用");
}

关键注意事项 #

• 确保JWT中提取的用户标识（如sub）与CustomUserDetailsService.loadUserByUsername()的查询参数完全匹配（你的代码中是用用户ID查询，所以JWT的sub需存储用户ID）。
• 如果不需要合并JWT权限，可直接使用userDetails.getAuthorities()作为认证权限集合。
• 若JWT解析或用户查询失败，需捕获UsernameNotFoundException等异常，可结合全局异常处理器返回友好提示。

内容的提问来源于stack exchange，提问作者dragontrainer