Spring Boot OAuth2 JWT环境下@AuthenticationPrincipal返回null问题

在OAuth2资源服务器（JWT模式）下，Spring Security默认会将JWT解析为JwtAuthenticationToken，其认证主体是Jwt对象，而非你自定义的User实体。直接用@AuthenticationPrincipal User接收时，因为类型不匹配，Spring无法完成绑定，所以返回null。

方案一：自定义JWT认证转换器，将Jwt转换为User实体 #

通过自定义JwtAuthenticationConverter，在解析JWT时自动从数据库加载对应的User对象，替换默认的Jwt主体。

1. 完善安全配置类中的jwtAuthenticationConverter()方法，注入UserDetailsService：

@Autowired
private UserDetailsServiceImpl userDetailsService;

private JwtAuthenticationConverter jwtAuthenticationConverter() {
    JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
    
    // 配置权限转换器（根据你的JWT claim结构调整，比如从"roles"或"authorities"提取权限）
    converter.setJwtGrantedAuthoritiesConverter(jwt -> {
        List<String> roles = jwt.getClaimAsStringList("roles");
        return roles.stream()
                .map(role -> new SimpleGrantedAuthority("ROLE_" + role))
                .collect(Collectors.toList());
    });
    
    // 配置主体转换器：从JWT中获取用户名，加载User实体
    converter.setPrincipalConverter(jwt -> {
        String username = jwt.getClaimAsString("username"); // 确保JWT包含username字段
        return userDetailsService.loadUserByUsername(username);
    });
    
    return converter;
}

2. 此时控制器中的@AuthenticationPrincipal User就能正常获取到用户对象：

@GetMapping("/test")
public ResponseEntity<String> getUserById(@AuthenticationPrincipal User userDetails) {
    System.out.println(userDetails.getUserId()); // 正常输出用户ID
    return new ResponseEntity<>("test response message", HttpStatus.OK);
}

方案二：直接获取Jwt对象，手动查询用户 #

如果不想全局转换主体，可以在控制器中直接接收Jwt对象，从中提取信息后查询数据库：

@RestController
@RequestMapping("/user")
public class UserController {

    @Autowired
    private UserDetailsServiceImpl userDetailsService;

    @GetMapping("/test")
    public ResponseEntity<String> getUserById(@AuthenticationPrincipal Jwt jwt) {
        String username = jwt.getClaimAsString("username");
        User user = (User) userDetailsService.loadUserByUsername(username);
        System.out.println(user.getUserId());
        return new ResponseEntity<>("test response message", HttpStatus.OK);
    }
}

• 确保你的JWT中包含能唯一标识用户的字段（比如username或user_id），这样才能正确查询到对应的User实体。
• 方案一每次请求都会查询数据库，如果性能要求高，可以添加缓存（比如用Spring Cache缓存User对象）。
• 确认JWT的解析配置正确（比如签名密钥、claim映射），保证能正确提取所需字段。

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