如何在Keycloak的access_token中返回角色绑定的权限信息

问题场景 #

• 已在Keycloak中创建ADMIN、GUEST、SUPERADMIN三个角色，其中SUPERADMIN角色绑定了read、write、gestion三类权限，对应权限标识为p_Read、p_Write、p_gestion
• SUPERADMIN角色权限配置参考：
  
• 使用Postman调用接口以SUPERADMIN账号登录获取access_token，解码后基础身份字段均正常，但未包含上述三个自定义权限字段，解码后的令牌内容如下：

"iat": 1654784756,
"jti": "6bc716df-66fc-47ad-9eaf-8ef252969c61",
"iss": "https://dev.mydomain.com/auth/realms/Licenses",
"aud": "account",
"sub": "55552ce7-3f92-49a7-835f-7cd356a34d7e",
"typ": "Bearer",
"azp": "Licenses",
"session_state": "1cb9ac94-0d53-423c-9cd6-66472c8ce02b",
"acr": "1",
"realm_access": {
  "roles": [
    "SUPERADMIN",
    "offline_access",
    "default-roles-licenses",
    "uma_authorization"
  ]
},
"resource_access": {
  "Licenses": {
    "roles": [
      "SUPERADMIN"
    ]
  },
  "account": {
    "roles": [
      "manage-account",
      "manage-account-links",
      "view-profile"
    ]
  }
},
"scope": "openid email profile",
"email_verified": false,
"name": "Pepe",
"preferred_username": "pepe@user.com",
"given_name": "Pepe",
"family_name": "Pepe",
"email": "pepe@user.com"

核心原因 #

不是操作失误，是Keycloak默认行为和配置缺失共同导致的：

1. 你当前配置的是Keycloak细粒度授权服务（Authorization Services）下的资源权限，这类权限不属于默认会写入令牌的字段，默认只会把角色列表写入realm_access、resource_access节点
2. 客户端未开启授权功能、未配置权限字段到令牌的映射规则
3. 请求令牌时未携带授权服务要求的专属scope

解决方案 #

根据你的权限复杂度选一种方案即可：

方案1：保留细粒度授权配置（适合需要动态权限控制的场景） #

按以下顺序修改配置：

• 进入Licenses客户端详情页，打开Authorization Enabled开关，保存配置
• 切换到客户端的Mappers标签页，新建两个映射器：
  1. 受众映射：类型选Audience，名称自定义，Included Client Audience选择Licenses客户端，打开Add to access token开关后保存
  2. 权限声明映射：类型选Permission Claim，名称自定义，声明名称可填permissions，打开Add to access token开关后保存
• 修改Postman取token的请求参数，scope字段原值是openid email profile，追加 Licenses/permission，即完整值为openid email profile Licenses/permission
  重新获取令牌解码后，就能在authorization.permissions节点下找到你配置的三个权限标识。

方案2：简化权限映射（适合固定权限标识的轻量场景） #

如果不需要用到Keycloak细粒度授权的动态策略能力，不用走授权服务配置，操作更简单：

• 删掉之前在Authorization菜单下配的资源、权限规则，直接进入SUPERADMIN角色详情页，在Attributes标签下添加属性，键名填permission，值分别填p_Read、p_Write、p_gestion三个值，保存
• 进入Licenses客户端的Mappers标签页，新建映射器，类型选Role Attribute，配置：
  • Name：自定义
  • Role attribute：填permission
  • Token Claim Name：填你要在令牌里显示的字段名，比如permissions
  • 打开Add to access token开关，保存
    不用修改取token的请求参数，重新获取令牌就能直接看到自定义的权限字段。

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