Keycloak从v6.0.1迁移至v18.0.2后出现账户未完全设置错误

问题背景 #

从Keycloak v6.0.1迁移至v18.0.2后，新用户登录时返回错误：

{"error":"invalid_grant","error_description":"Account is not fully set up"}

已取消「Authorization > Required Actions」模块中的「Update Password」选项，但依赖密码登录的用户仍报错；将Credential Type设为TOTP时问题解决，且UI的Required Actions中无条目，但数据库user_required_action表存在相关记录。

原因分析 #

Keycloak版本升级后，UI配置与数据库记录存在不同步情况，用户创建时可能被默认添加了未在UI展示的UPDATE_PASSWORD必填操作，导致密码登录时触发校验失败。

解决方案 #

1. 清理数据库残留的必填操作记录 #

直接删除user_required_action表中对应用户的UPDATE_PASSWORD相关条目，或者使用Keycloak Admin API批量处理：

# 替换占位符为实际信息，删除指定用户的UPDATE_PASSWORD必填操作
curl -X DELETE "http://{keycloak-domain}/admin/realms/{realm-name}/users/{user-id}/required-actions/UPDATE_PASSWORD" \
-H "Authorization: Bearer {admin-access-token}"

2. 同步UI与后端配置 #

• 进入Realm设置 → 用户 → Required Actions，确认所有不需要的必填操作已被禁用
• 检查Realm的Authentication → Flows，确保密码登录流程中没有强制要求完成未设置的操作

3. 规范用户创建流程 #

• 新建用户时，手动清除该用户的所有默认必填操作
• 若使用脚本或自动化工具创建用户，确保代码中未自动添加UPDATE_PASSWORD等不必要的必填操作

4. 验证密码登录用户的凭证状态 #

• 确认用户的Credential Type为Password且已设置有效密码
• 检查用户详情页的Required Actions标签，确保无遗留操作项

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