本文详解如何在 Quarkus 中正确配置 JWT 角色校验，解决因使用非标准 groups 声明（如 Microsoft WS-Federation 风格的 namespaced role claim）导致 @RolesAllowed 失效的问题。
本文详解如何在 quarkus 中正确配置 jwt 角色校验，解决因使用非标准 `groups` 声明（如 microsoft ws-federation 风格的 namespaced role claim）导致 `@rolesallowed` 失效的问题。
在 Quarkus 中启用基于 JWT 的声明式角色访问控制（如 @RolesAllowed({"Admin"})）时，框架默认仅识别标准的 groups（或 realm_access.roles、resource_access.{client}.roles）作为角色来源。然而，您的 JWT 使用的是 Microsoft Identity Model 兼容的命名空间化声明：
{
"http://schemas.microsoft.com/ws/2008/06/identity/claims/role": ["Admin", "Developer"],
"exp": 1677257784,
"iss": "IMS.company.com",
// ...其他声明
}该声明路径不符合 Quarkus 默认约定，因此即使令牌中包含 "Admin"，@RolesAllowed({"Admin"}) 仍会拒绝所有请求——因为 Quarkus 未从中提取任何有效角色。
✅ 正确解决方案：配置自定义角色声明路径
通过 smallrye.jwt.path.groups 配置项，可显式指定 JWT 中存放用户角色数组的 JSON 路径（支持嵌套路径和 URI 格式键名）。针对您的 JWT，需在 application.properties 中添加：
# 指向 Microsoft 风格的 role 声明路径（注意：URI 中的斜杠需转义为 \/） smallrye.jwt.path.groups=http://schemas.microsoft.com\/ws/2008\/06\/identity\/claims\/role
⚠️ 注意：由于 : 和 / 在 properties 文件中具有特殊含义，必须对 URI 中的 / 进行双重转义（\/）；冒号 : 不需转义，但整个路径应作为字符串字面量处理。若使用 YAML（application.yml），可避免转义问题：
smallrye: jwt: path: groups: "http://schemas.microsoft.com/ws/2008/06/identity/claims/role"
? 验证与调试建议
-
启用 JWT 解析日志（开发阶段）：
quarkus.log.category."io.smallrye.jwt".level=DEBUG
查看日志中是否成功解析出 groups = [Admin, Developer]。
-
确保签名验证通过：
您的 JWT header 中 alg 值为 "http://www.w3.org/2001/04/xmldsig-more#hmac-sha256"，这属于非标准算法标识符。SmallRye JWT 默认仅支持 HS256、RS256 等 IANA 注册值。若使用 HMAC 签名，请改用标准算法名并配置密钥：mp.jwt.verify.issuer=IMS.company.com mp.jwt.verify.public-key-location=classpath:public-key.pem # 或 HS256 密钥 # 若为 HS256： # mp.jwt.verify.secret-key=your-32-byte-secret-key
角色匹配是大小写敏感的：
@RolesAllowed({"Admin"}) 中的 "Admin" 必须与 JWT 中数组元素的字符串完全一致（包括大小写与空格）。
✅ 完整工作示例
application.properties：
mp.jwt.verify.issuer=IMS.company.com smallrye.jwt.path.groups=http://schemas.microsoft.com\/ws/2008\/06\/identity\/claims\/role # 启用 JWT 安全上下文（必需） quarkus.smallrye-jwt.enabled=true
REST 端点（无需修改）：
@GET
@Produces(MediaType.APPLICATION_JSON)
@Path("/getAllOverview")
@RolesAllowed({"Admin"})
public String getAllOverview() {
return "Admin-only data";
}只要 JWT 有效且 http://schemas.microsoft.com/ws/2008/06/identity/claims/role 数组包含 "Admin"，请求即可通过授权。
? 总结
- Quarkus 不自动识别任意命名的 role 声明，必须通过 smallrye.jwt.path.groups 显式配置；
- URI 类型声明键名在 .properties 中需谨慎转义 /；
- 始终验证 JWT 签名算法兼容性与密钥配置；
- 利用 DEBUG 日志确认角色是否被正确加载，这是排查授权失败的最快方式。
遵循以上配置，您即可无缝集成企业级 SSO 发放的标准化 JWT，并安全启用细粒度角色访问控制。
