Keycloak 24与Terraform mrparkers 4.4.0中如何为专属客户端范围添加映射器

核心问题分析 #

专属客户端范围是绑定到特定客户端的私有范围，并非全局客户端范围，因此直接用keycloak_openid_client_scope数据源查询会找不到（该数据源仅针对全局范围）。此外常见错误是把Realm的显示名称当成realm_id传入，而Keycloak要求realm_id必须是Realm的UUID。

分步解决方案 #

1. 修正Realm ID的获取方式 #

确保Terraform使用Realm的UUID而非显示名称：

data "keycloak_realm" "drivers" {
  realm = "drivers" # 此处填写Realm的显示名称
}

2. 获取专属范围所属的客户端信息 #

先定位到专属范围绑定的目标客户端：

data "keycloak_openid_client" "target_client" {
  realm_id = data.keycloak_realm.drivers.id
  name     = "你的客户端显示名称" # 也可使用client_id字段，根据实际情况选择
}

3. 获取专属客户端范围的ID（二选一） #

方式一：通过Keycloak API查询（适用于手动创建的专属范围）

1. 先获取管理员Token：

curl -X POST "http://你的Keycloak地址/realms/master/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=管理员账号&password=管理员密码&grant_type=password&client_id=admin-cli"

2. 用Token查询该客户端的专属范围：

curl -X GET "http://你的Keycloak地址/realms/drivers/clients/${data.keycloak_openid_client.target_client.id}/client-scopes" \
  -H "Authorization: Bearer 上述获取的Token"

从返回的JSON结果中，找到目标专属范围的id字段值。

方式二：用Terraform创建专属范围（适用于尚未创建范围的场景）

如果专属范围还未创建，直接用Terraform创建并自动获取ID：

resource "keycloak_openid_client_scope" "loadboard_dedicated_scope" {
  realm_id  = data.keycloak_realm.drivers.id
  client_id = data.keycloak_openid_client.target_client.id # 绑定到目标客户端
  name      = "loadboard-dedicated" # 专属范围名称
}

4. 添加映射器到专属范围 #

无论通过哪种方式获取到专属范围ID，都可以用以下代码添加映射器：

resource "keycloak_openid_client_scope_mapper" "loadboard_mapper" {
  realm_id        = data.keycloak_realm.drivers.id
  client_scope_id = "上述获取的专属范围ID" # 若为Terraform创建，填写keycloak_openid_client_scope.loadboard_dedicated_scope.id
  name            = "loadboard-id-mapper" # 映射器名称
  mapper_type     = "oidc-usermodel-attribute-mapper" # 替换为你需要的映射器类型，如oidc-hardcoded-claim-mapper等

  # 映射器配置，根据需求调整
  config = {
    user.attribute       = "loadboardId" # 关联的用户属性
    claim.name           = "loadboard_id" # 生成的Claim名称
    jsonType.label       = "String" # Claim类型
    add.to.id.token      = "true"
    add.to.access.token  = "true"
    add.to.userinfo      = "true"
  }
}

额外检查项 #

• 确保Terraform使用的Keycloak账号拥有realm-admin角色，具备客户端和范围的管理权限。
• 确认专属范围的名称与Keycloak UI中显示的完全一致，注意大小写和特殊字符。

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