Keycloak自定义忘记密码流程（邮箱/TOTP二选一）故障求助

一、认证流配置排查 #

这是最可能导致跳过选择界面的核心原因，按以下步骤检查：

1. 流结构与节点顺序
   • 复制默认Reset Credentials流创建自定义流，确保在Username Validation节点后添加交互式表单节点（命名为Recovery Method Selection），该节点必须是用户需要手动操作的类型，而非自动执行节点。
   • 给该表单节点配置单选框字段，选项为「邮箱恢复」和「TOTP验证」，并设置表单提交目标为Keycloak认证端点。
2. 分支条件配置
   • 添加条件执行器：判断用户是否存在TOTP凭据（通过user.credentialManager().getStoredCredentialsByType("totp")校验），仅当存在TOTP时才显示Recovery Method Selection节点；无TOTP则直接跳过，进入邮箱恢复流程。
   • 检查节点的Required属性：将选择节点设为Required，避免被自动跳过；同时确保后续的邮箱/TOTP验证节点根据选择的参数动态触发。
3. 流关联验证
   • 在Realm的Authentication → Required Actions中，确认Reset Password已关联到你创建的自定义流，而非默认流。

二、主题模板与变量排查 #

1. 模板渲染逻辑
   • 在自定义主题的forgot-password.ftl中，添加条件渲染代码，确保仅当用户有TOTP时才显示选择选项：

     <#if authSession.getAuthNote("hasTotp") == "true">
       <div class="form-group">
         <label>选择恢复方式:</label>
         <div class="radio">
           <label><input type="radio" name="recoveryMethod" value="email" checked>邮箱恢复</label>
         </div>
         <div class="radio">
           <label><input type="radio" name="recoveryMethod" value="totp">TOTP验证</label>
         </div>
       </div>
     </#if>
     

2. 变量传递校验
   • 确认自定义Authenticator或脚本执行器已将hasTotp状态存入认证会话：

     var totpCredentials = context.getUser().credentialManager().getStoredCredentialsByType("totp");
     var hasTotp = totpCredentials != null && totpCredentials.size() > 0;
     context.getAuthenticationSession().setAuthNote("hasTotp", hasTotp.toString());
     

   • 避免模板中错误地直接隐藏选择界面，或表单提交地址指向应用而非Keycloak认证端点。

三、JavaScript集成排查 #

1. 后端脚本逻辑
   • 检查脚本执行器中是否提前调用了context.success()，这会直接完成认证流程，跳过用户交互步骤。仅当不需要用户操作时（如无TOTP直接走邮箱）才调用该方法。
2. 前端提交逻辑
   • 确保表单提交时正确携带recoveryMethod参数，让Keycloak识别用户选择的恢复方式：

     document.getElementById('recovery-form').addEventListener('submit', function(e) {
       var selectedMethod = document.querySelector('input[name="recoveryMethod"]:checked').value;
       this.action += (this.action.includes('?') ? '&' : '?') + 'recoveryMethod=' + selectedMethod;
     });
     

四、实现方式正确性确认 #

你期望的「邮箱/TOTP二选一恢复」流程是完全可行的，正确的实现路径为：

1. 扩展Reset Credentials认证流，添加交互式选择节点；
2. 通过脚本执行器动态判断用户TOTP状态，控制节点显示；
3. 主题模板根据会话变量渲染对应选项；
4. 后端根据提交的recoveryMethod参数，触发对应的验证流程，验证通过后进入改密页面。

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