新建Keycloak Realm无法为Quarkus应用登录提供角色权限

问题诊断 #

核心原因是Keycloak颁发的JWT令牌未包含groups、realm_access/roles等必要权限声明，导致Quarkus应用无法完成用户权限校验，进而返回403错误。以下是针对性修复步骤：

修复步骤 #

1. 检查客户端默认客户端范围配置 #

进入Keycloak管理控制台的oqm Realm，找到Clients -> oqm-app -> Client Scopes：

• 确认roles和groups这两个内置客户端范围已添加到Assigned Default Client Scopes列表
• 若未添加，从Available Client Scopes中选中这两个，点击Add to Default按钮

2. 配置客户端角色映射 #

在Clients -> oqm-app -> Role Mappings页面：

• 切换到Realm Roles标签，将需要暴露给应用的角色（如inventoryAdmin）从Available Roles添加到Assigned Roles
• 若使用组角色，确认目标组（如admins）的角色已正确继承到用户，且客户端有权限获取这些角色

3. 调整令牌生成设置 #

进入Clients -> oqm-app -> Advanced -> Token Settings：

• 开启Include Realm Roles in Access Token和Include Client Roles in Access Token选项
• 针对组信息，按需配置Group Attribute Name或Full Group Path，确保组数据能被写入令牌

4. 修正Quarkus应用OIDC配置 #

在应用的application.properties中补充或调整配置：

# Keycloak认证服务器地址
quarkus.oidc.auth-server-url=http://<your-keycloak-host>/realms/oqm
# 客户端ID
quarkus.oidc.client-id=oqm-app
# 客户端密钥（客户端为confidential类型时必填）
quarkus.oidc.credentials.secret=<your-client-secret>
# 指定令牌受众
quarkus.oidc.token.audience=oqm-app
# 映射Keycloak realm角色到Quarkus安全角色
quarkus.security.jwt.roles.claim-path=realm_access/roles

5. 验证令牌内容 #

• 用jwt.io或Keycloak内置工具解析KEYCLOAK_IDENTITY令牌，确认是否包含realm_access、groups字段
• 检查新注册用户是否自动加入admins默认组（可在Keycloak的Users -> 目标用户 -> Groups标签查看）

常见排查点 #

• 确认客户端oqm-app的Access Type设为confidential（因开启了客户端认证），且Quarkus配置中的客户端密钥与Keycloak一致
• 检查用户的角色分配、组的角色继承关系是否正常

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