Keycloak 20.0.3配置：生成含groups的JWT适配WildFly MicroProfile-JWT

问题背景 #

你正在尝试将WildFly的microprofile-jwt快速启动示例适配到Keycloak 20.0.3，当前配置的microprofile-config.properties如下：

mp.jwt.verify.publickey.location=http://localhost:8280/realms/mp_jwt_realm/protocol/openid-connect/certs
mp.jwt.verify.issuer=http://localhost:8280/realms/mp_jwt_realm

示例依赖JWT载荷中的groups字段做权限控制，但Keycloak生成的JWT仅包含realm_access.roles和resource_access.<client>.roles结构，无groups字段，导致访问需要Subscriber角色的/microprofile-jwt/Sample/subscription接口返回403 Forbidden，而无权限要求的/helloworld接口可正常访问。

解决步骤 #

要让Keycloak生成的JWT包含groups字段，需为目标客户端添加令牌映射器，具体操作如下：

1. 登录Keycloak管理控制台，进入mp_jwt_realm领域
2. 切换到Clients页面，选中你的microprofile-jwt客户端
3. 进入客户端的Mappers标签页，点击Create按钮
4. 在映射器配置页填写以下参数：
   • Name: 自定义名称（如Groups-Realm-Roles）
   • Mapper Type: 选择User Realm Role
   • Token Claim Name: 输入groups
   • Claim JSON Type: 选择String
   • Add to access token: 开启
   • Multivalued: 开启（让多角色以数组形式返回）
   • Full group path: 关闭（仅返回角色名称）
5. 点击Save完成配置

如果需要将客户端角色也加入groups字段，可重复上述步骤，将Mapper Type改为User Client Role即可。

验证效果 #

重新获取JWT令牌并解码，应能看到groups字段包含Subscriber等角色，此时再访问/subscription接口即可正常通过权限校验。

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