如何在Keycloak中添加自定义字段（属性）支持注册及后端填充？

一、控制台配置：让自定义属性出现在注册表单 #

1. 登录Keycloak管理控制台，进入目标Realm
2. 左侧菜单选择用户 -> 用户属性（User Attributes）
3. 点击「添加属性」，输入属性名（比如employee_id），设置以下参数：
   • 显示名称：前端注册表单上显示的文本（比如“员工ID”）
   • 必填：勾选则用户注册时必须填写
   • 在注册表单显示：必须勾选，否则用户看不到这个字段
   • 其他参数（比如正则校验、帮助文本）按需配置
4. 保存后，确保注册流程能渲染这些字段：
   • 左侧菜单选择认证 -> 流程（Authentication -> Flows）
   • 找到「注册」（Registration）流程，点击「编辑」
   • 检查流程里的「User Profile」或「Registration User Creation」步骤是否启用，确保它会读取并展示你添加的自定义属性
   • 若要调整表单字段顺序，可进入「认证 -> 表单」（Authentication -> Forms），编辑对应的注册表单进行调整

二、后端服务通过API填充自定义属性 #

Keycloak提供Admin REST API来管理用户属性，具体步骤如下：

1. 获取管理员Token #

先用具备manage-users权限的账号获取访问令牌，示例curl请求：

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

返回结果中的access_token就是后续API调用所需的令牌。

2. 更新用户自定义属性 #

调用/users/{userId}接口，用PUT或PATCH方法更新属性：

• PATCH方式（推荐，仅修改目标属性）：

curl -X PATCH "http://your-keycloak-domain/auth/admin/realms/your-realm/users/{user-id}" \
  -H "Authorization: Bearer {access-token}" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "op": "replace",
      "path": "/attributes/department",
      "value": ["技术部"]
    },
    {
      "op": "add",
      "path": "/attributes/employee_id",
      "value": ["EMP001"]
    }
  ]'

• PUT方式（全量更新，需包含原有字段避免覆盖）：

curl -X PUT "http://your-keycloak-domain/auth/admin/realms/your-realm/users/{user-id}" \
  -H "Authorization: Bearer {access-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "user123",
    "email": "user123@example.com",
    "attributes": {
      "department": ["技术部"],
      "employee_id": ["EMP001"]
    },
    // 保留用户原有字段，比如firstName、lastName等
  }'

3. 权限注意事项 #

• 调用API的账号（或服务账号）需要在目标Realm下拥有manage-users角色（可在「角色 -> Realm角色」中找到并分配）
• 如果用客户端凭证模式（适合后端服务），需创建专用客户端，开启「服务账号启用」，并给该客户端分配manage-users角色

三、验证效果 #

• 用户注册时，会看到添加的自定义字段，填写后会保存到用户属性中
• 后端调用API后，可在Keycloak控制台的用户详情页「属性」标签下查看更新后的字段

内容的提问来源于stack exchange，提问作者Ghassen Jemaï