为何getUserPrincipal()并非KeycloakPrincipal实例？Quarkus问题咨询

问题背景 #

我在开发Quarkus+Keycloak项目时，想通过KeycloakPrincipal获取登录用户ID，但sc.getUserPrincipal()返回的实例并非KeycloakPrincipal，原有代码逻辑走不通。Token Payload里明确有sub字段（即用户ID），但无法通过Keycloak专属类获取。

核心原因 #

Quarkus默认采用**MicroProfile JWT（MP-JWT）**作为认证实现时，SecurityContext返回的Principal是MP-JWT的标准实现类，而非Keycloak的KeycloakPrincipal。只有当你使用Quarkus的Keycloak OIDC扩展时，才会返回KeycloakPrincipal实例。

排查方向 #

• 检查依赖配置：查看项目pom.xml（或build.gradle），如果引入的是quarkus-smallrye-jwt，那当前是MP-JWT模式；需要换成quarkus-oidc扩展才能用KeycloakPrincipal。
• 核对application配置：如果是OIDC模式，配置项应该以quarkus.oidc.*开头（比如quarkus.oidc.auth-server-url）；如果是MP-JWT模式，配置项是quarkus.smallrye-jwt.*，这种模式下不会生成KeycloakPrincipal。
• 确认认证机制：Quarkus中，Keycloak作为OIDC提供商，需要启用OIDC认证扩展，而非纯MP-JWT认证。

解决方法 #

方案1：切换到OIDC模式，使用KeycloakPrincipal #

1. 添加OIDC依赖：

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-oidc</artifactId>
</dependency>

2. 配置application.properties：

# Keycloak认证服务器地址
quarkus.oidc.auth-server-url=http://localhost:8180/realms/quarkus
# 客户端ID，对应Keycloak里创建的客户端
quarkus.oidc.client-id=quarkus-app
# 如果是保密客户端，需要配置密钥
quarkus.oidc.credentials.secret=your-client-secret

3. 配置完成后，sc.getUserPrincipal()会返回KeycloakPrincipal实例，原有代码逻辑即可正常获取用户ID。

方案2：直接通过MP-JWT获取用户ID（无需切换认证） #

既然Token Payload里已经包含sub字段，也可以直接用MP-JWT的API获取，不用依赖Keycloak专属类：

@Path("/api/users")
public class UserResource {
    @Inject
    JsonWebToken jwt;

    @GET
    @Path("/me")
    @NoCache
    public String me() {
        // sub字段就是用户ID
        return jwt.getSubject();
    }
}

或者通过SecurityContext直接解析：

@Context
SecurityContext sc;

@GET
@Path("/me")
@NoCache
public String me() {
    JsonWebToken jwt = (JsonWebToken) sc.getUserPrincipal();
    return jwt.getSubject();
}

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