Keycloak用户创建流程添加自定义字段的实现方案咨询

1. 配置Realm级用户自定义属性 #

首先要在Keycloak中定义需要的自定义字段，全局生效：

• 登录Keycloak管理控制台，进入目标Realm，打开用户配置文件配置页（Keycloak 19+版本直接在左侧菜单栏可见，低版本路径为Realm设置 > 用户配置文件）
• 切换到属性标签，点击创建属性，依次添加所需的自定义参数，核心配置项如下：
  • 名称：自定义参数的唯一键名，后续REST传参、查询都用该值作为字段名
  • 权限配置：勾选管理员可编辑、用户可编辑，保证接口调用时有写入权限
  • 可选配置：可按需求添加必填校验、正则规则、字段分组等配置
• 所有属性添加完成后，点击页面右上角的保存使配置生效

2. REST接口创建用户时传入自定义参数 #

调用官方用户创建接口POST /{realm}/users时，在请求体中添加attributes字段，将自定义参数以键值对形式放入即可，参考请求示例：

{
  "username": "test001",
  "email": "test001@example.com",
  "enabled": true,
  "credentials": [
    {
      "type": "password",
      "value": "Test@1234",
      "temporary": false
    }
  ],
  "attributes": {
    "phone": ["13800138000"],
    "dept_id": ["2001"],
    "employee_id": ["E12345"]
  }
}

注意：Keycloak的用户属性值默认以数组格式存储，即使是单值场景也需要将参数值包裹在[]中，否则会出现格式错误

3. 配置自定义参数可被查询返回 #

分两种场景配置，覆盖不同查询需求：

3.1 管理员接口查询 #

无需额外配置，调用用户查询接口GET /{realm}/users/{userId}、用户列表查询接口GET /{realm}/users时，返回结果会默认携带完整的attributes字段，包含所有自定义参数值。

3.2 普通用户查询（用户信息接口/Token获取） #

如果需要普通用户登录后通过用户信息接口、ID Token/Access Token拿到自定义参数，需要额外配置客户端映射：

• 进入目标客户端的客户端范围页，点击进入默认绑定的profile范围
• 切换到映射器标签，点击添加映射器 > 按配置，选择用户属性类型
• 填写自定义属性的键名、Token声明名称，按需勾选添加到ID令牌、添加到访问令牌、添加到用户信息选项后保存
• 配置完成后，调用GET /{realm}/protocol/openid-connect/userinfo接口，或解析用户登录返回的Token，即可拿到对应的自定义参数值

4. 功能验证 #

• 调用用户创建接口后，直接调用管理员侧用户查询接口，检查返回的attributes字段是否和传入的自定义参数一致
• 用新建用户登录，调用用户信息接口，确认配置过映射的自定义参数可正常返回
• 如需修改自定义参数，调用用户更新接口PUT /{realm}/users/{userId}，覆盖attributes字段的对应值即可

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