如何在Keycloak客户端角色中添加自定义属性？

UI操作步骤 #

• 登录Keycloak管理控制台，选中目标Realm
• 进入「Clients」页面，找到需要配置的客户端并点击进入详情
• 切换到「Roles」标签页，选择要添加属性的角色（或点击「Add Role」新建角色）
• 在角色详情页的「Attributes」板块，输入属性的键和值，点击「Add」按钮完成保存

API批量/自动化配置方式 #

如果需要批量操作或集成到自动化流程，可使用Keycloak Admin API：

1. 先通过/auth/realms/master/protocol/openid-connect/token接口，用管理员账号密码获取访问令牌
2. 发送PUT请求更新角色属性，示例命令：

curl -X PUT \
  http://your-keycloak-domain/auth/admin/realms/your-realm/clients/your-client-id/roles/your-role-name \
  -H "Authorization: Bearer your-admin-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "your-role-name",
    "attributes": {
      "custom_role_attr1": "attr_value1",
      "custom_role_attr2": "attr_value2"
    }
  }'

关键注意事项 #

• 客户端角色的属性存储逻辑和用户属性完全独立，不能直接复用用户属性的添加路径
• 若需要将角色自定义属性包含在ID Token或Access Token中，需在客户端的「Mappers」中添加映射器：
  • 选择「User Client Role」类型，开启对应Token的添加选项
  • 若需要更灵活的属性映射，可使用「Script Mapper」，示例脚本：

// 获取用户在目标客户端的所有角色
var clientRoles = user.getClientRoles("your-client-id");
clientRoles.forEach(role => {
  var roleAttrs = role.getAttributes();
  // 将角色属性添加到token的自定义claim中
  if (roleAttrs.hasOwnProperty("custom_attr")) {
    token.setClaim(`role_${role.getName()}_custom_attr`, roleAttrs.custom_attr);
  }
});

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