如何在Spring Boot 3中通过OAuth提取Keycloak Principal？

Spring Boot 3搭配Spring Security 6后，Keycloak的认证集成已统一采用Spring Security标准的OAuth2/JWT认证模型，不再使用旧版本中的KeycloakAuthenticationToken，以下是几种提取Principal的方式：

方式一：通过JwtAuthenticationToken获取Jwt（推荐） #

直接转换为Spring Security提供的JwtAuthenticationToken，其getPrincipal()返回的Jwt对象本身实现了Principal接口，同时还能获取令牌中的所有声明信息：

import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationToken;

// 获取当前认证对象
Authentication authentication = SecurityContextHolder.getContext().getAuthentication();

if (authentication instanceof JwtAuthenticationToken jwtAuthToken) {
    // 获取Principal（Jwt类型）
    Jwt principal = jwtAuthToken.getPrincipal();
    
    // 示例：提取用户信息
    String userId = principal.getSubject();
    String userEmail = principal.getClaimAsString("email");
    String userName = principal.getClaimAsString("preferred_username");
} else {
    throw new UnauthorizedException("无效的Keycloak认证令牌");
}

方式二：通用Principal获取 #

如果不需要Jwt的额外声明，可直接获取通用的Principal对象：

import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;

Authentication authentication = SecurityContextHolder.getContext().getAuthentication();

if (authentication != null && authentication.isAuthenticated()) {
    Principal principal = authentication.getPrincipal();
    // 若需要Jwt信息，可强转为Jwt类型
    if (principal instanceof Jwt jwt) {
        // 处理Jwt声明
    }
} else {
    throw new UnauthorizedException("用户未通过Keycloak认证");
}

注意事项 #

• 确保项目已正确配置Spring Security OAuth2资源服务器依赖（如spring-boot-starter-oauth2-resource-server），并配置Keycloak的JWT验证信息（issuer、jwk-set-uri等）。
• 旧版本的KeycloakAuthenticationToken已被移除，无需再依赖Keycloak特定的Spring Boot starter，改用标准OAuth2依赖即可。

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