Keycloak Java客户端创建带自定义属性的角色失败求助

安全阿岳

2026-5-8

解决Keycloak 11.0.0 Admin Client创建角色时自定义属性被忽略的问题

我之前在使用Keycloak 11.0.0和对应版本的Admin Client时，也碰到过完全一样的问题——创建客户端角色时自定义属性总是被服务端忽略。后来排查发现这是该版本的一个小局限，通过分两步操作就能解决：

问题原因

Keycloak 11.0.0的角色创建端点（POST /{realm}/clients/{clientId}/roles）对attributes字段的处理存在缺陷，直接传递带属性的RoleRepresentation时，服务端不会持久化这些属性。但角色更新端点（PUT /{realm}/clients/{clientId}/roles/{roleName}）则能正确处理属性字段。

修复后的代码

我们可以先创建基础角色，再获取该角色并更新其属性：

public void createRole(String name) {
    // 第一步：创建不带属性的基础客户端角色
    RoleRepresentation roleRepresentation = new RoleRepresentation();
    roleRepresentation.setClientRole(true);
    roleRepresentation.setName(name);
    realm.clients().get(client.getId()).roles().create(roleRepresentation);

    // 第二步：获取刚创建的角色，添加自定义属性后更新
    RoleRepresentation createdRole = realm.clients().get(client.getId()).roles().get(name).toRepresentation();
    
    Map<String, List<String>> attributes = new HashMap<>();
    attributes.put("att1", Collections.singletonList("attribute1"));
    attributes.put("att2", Collections.singletonList("attribute2"));
    createdRole.setAttributes(attributes);
    
    realm.clients().get(client.getId()).roles().get(name).update(createdRole);
}