Keycloak更新客户端角色关联角色时PUT请求返回Bad Request问题

你遇到的问题是因为错误使用了角色更新接口：PUT /admin/realms/{realm}/roles/{role-name} 仅用于更新角色自身的基本属性（名称、描述、属性等），不能直接通过请求体中的composites字段修改复合角色的关联关系，这会触发Bad Request错误。

正确的复合角色关联更新方式 #

Keycloak提供了专门的接口来管理复合角色的关联：

1. 获取目标角色的ID

首先需要通过角色名称获取角色ID（复合角色接口依赖ID而非名称）：

GET /admin/realms/{realm}/roles/{role-name}

从返回结果中提取id字段（即你请求体中的0c80ac27-1788-4823-850c-8c2c0b53b6fa）。

2. 移除不需要的关联角色

如果需要移除现有关联，使用DELETE接口，请求体为要移除的角色对象（仅需核心字段）：

DELETE /admin/realms/{realm}/roles/{role-id}/composites

请求体示例（单个角色）：

{
    "id": "ad2202a3-836c-4431-a024-b29757b72389",
    "name": "TransportModeBus",
    "clientRole": true,
    "containerId": "b99076e7-1ebd-4085-a4ac-9a418cbfb8f3"
}

若需移除多个，可传入数组。

3. 添加新的关联角色

使用POST接口添加关联，请求体为要添加的角色对象数组：

POST /admin/realms/{realm}/roles/{role-id}/composites

请求体示例：

[
    {
        "id": "7014b0d6-0d54-4ff4-93bb-28a86d0ff34e",
        "name": "ParameterMgmtSearchView",
        "clientRole": true,
        "containerId": "b99076e7-1ebd-4085-a4ac-9a418cbfb8f3"
    },
    {
        "id": "28da2d61-a7d9-4d2d-bf95-449d2863d7f4",
        "name": "ParameterMgmtSearchEdit",
        "clientRole": true,
        "containerId": "b99076e7-1ebd-4085-a4ac-9a418cbfb8f3"
    }
]

额外注意事项 #

• 确保请求携带的Admin Token拥有manage-clients或manage-roles权限，否则会返回403。
• 客户端角色的containerId必须严格匹配所属客户端的ID，不能有误。
• 更新角色基本属性时，请求体不要包含composites字段，仅保留name、description、attributes等核心属性即可。

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