如何通过配置即代码管理Keycloak Realm的客户端默认角色？

一、管理Realm客户端默认角色的方法 #

1. REST API实现 #

Keycloak Admin API没有单独的客户端默认角色管理端点，但可以通过更新Realm的默认角色集合来实现。关键是客户端角色需要用client:<client-id>:<role-name>的格式标识：

• 先获取account客户端的ID：

  curl -X GET "http://<keycloak-host>/auth/admin/realms/<realm-name>/clients?clientId=account" \
  -H "Authorization: Bearer <admin-token>"
  

  从返回结果中提取id字段作为客户端ID，再获取该客户端下的角色列表：

  curl -X GET "http://<keycloak-host>/auth/admin/realms/<realm-name>/clients/<client-id>/roles" \
  -H "Authorization: Bearer <admin-token>"
  

• 将目标客户端角色添加到Realm默认角色：
  用PATCH请求更新Realm配置，把角色追加到defaultRoles数组：

  curl -X PATCH "http://<keycloak-host>/auth/admin/realms/<realm-name>" \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "op": "add",
      "path": "/defaultRoles/-",
      "value": "client:<client-id>:<role-name>"
    }
  ]'
  

2. Terraform配置实现 #

官方keycloak_default_roles资源仅支持全局角色，但可以通过keycloak_realm的default_roles参数直接配置客户端角色，同样使用client:<client-id>:<role-name>格式：

resource "keycloak_realm" "example" {
  realm   = "example-realm"
  enabled = true

  default_roles = [
    "offline_access",
    "uma_authorization",
    # 引用account客户端的角色，通过资源ID动态拼接
    "client:${keycloak_openid_client.account.id}:manage-account"
  ]
}

# 引用内置account客户端
resource "keycloak_openid_client" "account" {
  realm_id  = keycloak_realm.example.id
  client_id = "account"
  enabled   = true
}

二、实现仅管理员可编辑用户名/邮箱的权限控制 #

核心思路是拆分account客户端的角色权限，让普通用户只能获得受限的账号管理权限：

1. 拆分角色权限

   • 给account客户端创建新角色（比如manage-account-limited），只赋予修改非敏感信息（如姓名、手机号）的权限
   • 保留原manage-account角色的完整权限，仅分配给管理员组或用户

2. 更新默认角色
   将Realm默认角色中的manage-account替换为manage-account-limited，确保新用户自动获得受限权限

3. Terraform固化配置示例

# 创建受限的account客户端角色
resource "keycloak_role" "account_limited" {
  realm_id    = keycloak_realm.example.id
  client_id   = keycloak_openid_client.account.id
  name        = "manage-account-limited"
  description = "仅允许修改非敏感账号信息"
}

# 给受限角色分配允许的权限
resource "keycloak_role_scope_mapping" "account_limited_perms" {
  realm_id        = keycloak_realm.example.id
  role_id         = keycloak_role.account_limited.id
  client_scope_id = keycloak_openid_client.account.id

  roles = [
    "view-profile",
    "manage-profile" # 若该权限包含用户名/邮箱，需进一步拆分更细粒度的权限
  ]
}

# 更新Realm默认角色为受限角色
resource "keycloak_realm" "example" {
  realm   = "example-realm"
  enabled = true

  default_roles = [
    "offline_access",
    "uma_authorization",
    "client:${keycloak_openid_client.account.id}:manage-account-limited"
  ]
}

# 给管理员组分配完整的账号管理权限
resource "keycloak_group_role_mapping" "admin_account_full_access" {
  realm_id = keycloak_realm.example.id
  group_id = keycloak_group.admin.id

  client_id = keycloak_openid_client.account.id
  roles     = ["manage-account"]
}

另外，也可以直接在Keycloak控制台调整account客户端的授权策略：进入Clients > account > Authorization > Policies，修改manage-account对应的策略，仅允许管理员角色执行该操作。

内容的提问来源于stack exchange，提问作者Sirish Kumar Bethala