Keycloak非master域用户使用Admin REST API的权限要求及KC15升级403问题

核心问题原因 #

升级到KC15后返回的access token无角色声明，是因为KC15调整了客户端范围和令牌声明的默认配置，原有KC14的默认配置不再生效。

需检查的配置项 #

• 1. 确认角色分配正确
     需为非master域的操作用户分配当前域内置realm-management客户端下的realm-admin角色，注意不要误分配到master域的对应角色。
• 2. 调整admin-cli客户端的范围配置
     进入当前域的「客户端」列表，找到admin-cli进入配置页：
  • 切换到「客户端范围」标签，确认默认客户端范围中包含roles范围
  • 进入「客户端范围」->roles->「映射器」，找到「用户客户端角色」映射器，确认「包含在访问令牌中」开关开启，若映射器配置了「客户端ID」限制，需填入realm-management，或留空匹配所有客户端
• 3. 调整token请求的scope参数
     原有请求的scope仅为openid email profile，需新增roles参数，示例请求如下：

  curl --location --request POST 'https://<你的Keycloak域名>/auth/realms/<当前域名称>/protocol/openid-connect/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=admin-cli' \
  --data-urlencode 'username=<操作用户名>' \
  --data-urlencode 'password=<操作用户密码>' \
  --data-urlencode 'grant_type=password' \
  --data-urlencode 'scope=openid email profile roles'
  

• 4. 关闭域级细粒度权限开关（临时测试用）
     若以上配置完成后仍返回403，进入当前域的「管理->权限」页面，关闭「权限启用」开关测试。KC15默认强化了细粒度权限校验，若开启该开关，即使持有realm-admin角色也需要额外分配对应资源的操作权限。

验证标准 #

重新获取token后解码，能看到resource_access.realm-management.roles字段中包含realm-admin，即可正常调用Admin REST API。

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