如何重命名Keycloak领域角色？咨询UI外的实现途径

云原生阿岚

2026-7-29

Keycloak领域角色重命名方案

可以实现领域角色的重命名，目前Keycloak UI确实没有提供该功能，你可以通过以下两种方式操作：

使用Keycloak Admin REST API（推荐）

这是官方支持的安全方式，步骤如下：

获取管理员访问令牌
调用令牌接口获取access_token，示例请求：

curl -X POST "http://your-keycloak-domain/auth/realms/master/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=admin-cli" \
  -d "username=your-admin-username" \
  -d "password=your-admin-password" \
  -d "grant_type=password"

更新角色名称
使用获取到的access_token调用角色更新接口，替换{realm-name}为你的领域名称，{role-id}为目标角色的ID（可通过GET /admin/realms/{realm-name}/roles接口查询角色ID）：

curl -X PUT "http://your-keycloak-domain/auth/admin/realms/{realm-name}/roles/{role-id}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "new-role-name",
    "description": "可选：更新角色描述"
  }'

直接修改PostgreSQL数据库（不推荐）

直接操作数据库存在破坏数据一致性的风险，仅建议在应急场景下使用，操作前务必备份数据库：

连接到Keycloak的PostgreSQL实例。
执行SQL语句更新角色名称，替换your-realm-id、old-role-name、new-role-name为实际值：
```
UPDATE role SET name = 'new-role-name' WHERE realm_id = 'your-realm-id' AND name = 'old-role-name';
```
重启Keycloak服务，刷新内部缓存，确保修改生效。