如何配置Quarkus OIDC从自定义JWT的roles声明读取角色（替代默认groups）

核心配置调整 #

根据你同时使用quarkus-oidc和quarkus-keycloak-authorization的场景，分两种情况调整配置：

1. 仅依赖Quarkus OIDC的场景 #

直接在application.properties中指定角色声明路径：

# 配置从JWT的roles声明读取角色
quarkus.oidc.roles.role-claim-path=roles

• 确保JWT的roles字段为字符串数组格式（例如["APP_ADMIN", "USER"]）；如果是逗号分隔的单个字符串，需额外添加拆分配置：

# 若roles是逗号分隔的字符串，启用此配置拆分角色
quarkus.oidc.roles.role-claim-splitter=,

2. 同时启用Keycloak Authorization的场景 #

quarkus-keycloak-authorization扩展会独立处理角色来源，需要同步配置两层的角色声明路径：

# OIDC基础认证层的角色声明配置
quarkus.oidc.roles.role-claim-path=roles
# Keycloak授权策略层的角色声明配置
quarkus.keycloak-authorization.roles.role-claim-path=roles

排查验证步骤 #

• 注入SecurityIdentity打印角色，确认配置是否生效：

@Inject
SecurityIdentity identity;

public void checkCurrentRoles() {
    System.out.println("当前获取到的角色: " + identity.getRoles());
}

• 解码JWT确认roles字段确实存在于payload中，且格式与配置匹配（数组或可拆分的字符串）。

自定义角色转换器（兜底方案） #

如果上述配置仍无效，可通过自定义转换器强制提取角色：

1. 实现OidcRoleConverter接口：

import io.quarkus.oidc.runtime.OidcRoleConverter;
import io.quarkus.security.identity.SecurityIdentity;
import org.eclipse.microprofile.jwt.JsonWebToken;
import java.util.Collection;
import java.util.Collections;

public class CustomJwtRoleConverter implements OidcRoleConverter {
    @Override
    public Collection<String> convert(JsonWebToken jwt, SecurityIdentity identity) {
        // 从JWT的roles声明中提取角色集合
        Collection<String> roles = jwt.getClaim("roles");
        return roles != null ? roles : Collections.emptyList();
    }
}

2. 在配置文件中注册该转换器：

quarkus.oidc.roles.converter=com.yourpackage.CustomJwtRoleConverter

注：如果不需要Keycloak的细粒度权限控制，可以暂时移除quarkus-keycloak-authorization依赖，先验证纯OIDC的角色配置是否生效，再逐步集成授权功能。

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