如何从后端关闭Keycloak的OTP验证？集群误启用双因素认证无法登录

场景1：Realm级别强制启用了两步认证 #

如果是整个Realm开启了强制OTP认证，可通过以下两种方式关闭：

方法1：使用Keycloak Admin CLI #

1. 进入任意集群节点的Keycloak bin目录：

   cd /path/to/keycloak/bin
   

2. 使用管理员账号登录CLI（若管理员账号也受OTP限制，需先通过数据库重置其凭证）：

   ./kcadm.sh config credentials --server http://your-keycloak-domain:port/auth --realm master --user admin --password your-admin-password
   

3. 移除Realm的强制OTP配置动作：

   ./kcadm.sh update realms/your-realm-name -s "requiredActions=[]"
   

4. 若认证流程中添加了OTP执行器，需先获取执行器ID再删除：

   # 获取浏览器认证流程的所有执行器
   ./kcadm.sh get realms/your-realm-name/authentication/flows/browser/executions
   # 删除OTP执行器
   ./kcadm.sh delete realms/your-realm-name/authentication/flows/browser/executions/{target-execution-id}
   

方法2：直接操作共享数据库 #

1. 连接Keycloak集群使用的共享数据库
2. 查询目标Realm的ID：

   SELECT id FROM realm WHERE name = 'your-realm-name';
   

3. 删除Realm层面的强制OTP要求：

   DELETE FROM required_action WHERE realm_id = 'your-realm-id' AND name = 'CONFIGURE_TOTP';
   

4. 移除认证流程中的OTP执行器：

   DELETE FROM authentication_execution WHERE realm_id = 'your-realm-id' AND provider_id = 'totp';
   

5. 重启Keycloak集群所有节点，确保配置同步

场景2：单个用户被强制要求两步认证 #

如果仅特定用户受OTP限制，可按以下步骤处理：

方法1：Admin CLI方式 #

1. 登录CLI后，查询目标用户的ID：

   ./kcadm.sh get users -r your-realm-name -q username=target-username
   

2. 查看用户的所有凭证，找到OTP类型的凭证ID：

   ./kcadm.sh get users/{user-id}/credentials
   

3. 删除OTP凭证并移除强制配置动作：

   ./kcadm.sh delete users/{user-id}/credentials/{totp-credential-id}
   ./kcadm.sh update users/{user-id} -s "requiredActions=[]"
   

方法2：数据库操作 #

1. 查询目标用户的ID：

   SELECT id FROM user_entity WHERE username = 'target-username' AND realm_id = 'your-realm-id';
   

2. 删除用户的OTP凭证：

   DELETE FROM credential WHERE user_id = 'user-id' AND type = 'totp';
   

3. 移除用户的强制OTP配置动作：

   DELETE FROM user_required_action WHERE user_id = 'user-id' AND action = 'CONFIGURE_TOTP';
   

注意事项 #

• 操作数据库前必须备份数据库，防止数据丢失
• 集群环境下，数据库操作完成后需重启所有节点，保证配置同步
• 若管理员账号无法登录，可通过数据库重置管理员密码并移除其OTP凭证

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