Keycloak 22.0 REST API更新用户属性时清除邮箱问题求助

问题详情 #

将Keycloak从keycloak:21.0升级到keycloak:22.0后，调用PUT /admin/realms/<realm>/users/<user_id>接口出现异常：

• 当请求体仅传入属性字段时：

  {'attributes': {'myAttribute': 'XXXXX'}}
  

  会意外清除用户的邮箱字段。
• 当请求体仅传入必要操作字段时：

  {"requiredActions": ["required_action"]}
  

  无此副作用，用户邮箱保持正常。
• 该接口不支持PATCH方法，且在keycloak:21.0版本中无此问题。
• 当前临时方案：更新属性时在请求体中额外携带用户邮箱，但这种方式不符合接口设计逻辑，且仅邮箱字段受影响，其他用户属性未被修改。

解决思路 #

1. 核对Keycloak 22.0版本API变更 #

Keycloak 22.x可能调整了管理员REST API的PUT请求处理逻辑，比如默认启用了严格字段覆盖规则——未在请求体中明确传入的字段会被置空，而非保留原有值。优先查看官方版本变更日志，确认是否有用户更新接口的行为变更说明。

2. 基于完整用户数据发起PUT请求 #

如果暂时找不到根本原因，可以先通过GET接口获取用户完整数据，修改attributes后再完整提交，避免漏传字段导致意外清空：

1. 调用GET /admin/realms/<realm>/users/<user_id>获取用户全量信息
2. 修改返回数据中的attributes字段
3. 将修改后的完整数据通过PUT请求提交

3. 尝试启用PATCH方法支持 #

虽然当前接口显示不支持PATCH，可排查配置或尝试特定请求头：

• 检查Keycloak服务器配置，确认是否开启了PATCH方法的支持（如CORS相关配置）
• 尝试发送PATCH请求，设置Content-Type: application/merge-patch+json头，仅传入需要修改的attributes字段，验证是否能正常更新且不影响其他字段

4. 排查自定义扩展兼容性 #

如果部署了自定义用户存储提供者、事件监听器等扩展，升级到22.0后可能出现兼容性问题，导致PUT请求处理异常。可在干净的Keycloak 22.0实例中复现问题，确认是否由自定义扩展导致。

5. 提交官方Bug反馈 #

若确认是Keycloak官方版本问题，可向GitHub仓库提交Bug报告，详细说明版本、复现步骤、请求体及数据变化，帮助官方定位修复。

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