Keycloak多步骤认证流程中如何通过Href返回上一步

针对你在自定义三步认证流程中需要回退上一步的需求，以下是基于Keycloak原生机制的实现方案，确保不会引发会话异常或认证不一致：

核心思路：利用AuthenticationSession的Execution状态控制流程 #

Keycloak的认证流程每个步骤对应一个ExecutionModel，这些Execution的状态（SUCCESS/REQUIRED）会记录在AuthenticationSessionModel中。回退的本质是将流程指针重置到上一个已完成的步骤，同时重置后续步骤的状态为待执行。

1. 在自定义Authenticator中处理回退请求 #

在需要支持回退的步骤（比如第2、3步）的Authenticator类的action方法中，添加回退逻辑：

@Override
public void action(AuthenticationFlowContext context) {
    // 处理回退按钮提交的请求（假设按钮参数为action=back）
    FormParameters formParams = context.getHttpRequest().getDecodedFormParameters();
    if ("back".equals(formParams.getFirst("action"))) {
        AuthenticationSessionModel authSession = context.getAuthenticationSession();
        List<ExecutionModel> executions = authSession.getExecutions();
        
        // 找到最后一个已成功完成的步骤（排除当前步骤）
        ExecutionModel lastCompletedStep = null;
        for (ExecutionModel exec : executions) {
            if (exec.getStatus() == ExecutionModel.Status.SUCCESS 
                && !exec.getId().equals(context.getExecution().getId())) {
                lastCompletedStep = exec;
            } else if (exec.getStatus() == ExecutionModel.Status.REQUIRED) {
                // 遇到当前待执行步骤，停止遍历
                break;
            }
        }
        
        if (lastCompletedStep != null) {
            // 将当前及之后的所有步骤重置为REQUIRED状态
            for (ExecutionModel exec : executions) {
                if (exec.getIndex() >= lastCompletedStep.getIndex()) {
                    exec.setStatus(ExecutionModel.Status.REQUIRED);
                    authSession.updateExecution(exec);
                }
            }
            
            // 重置流程并跳转到上一步
            context.resetFlow();
            authSession.setAuthNote(AuthenticationProcessor.FLOW_PATH, lastCompletedStep.getFlowId());
            // 标记当前步骤处理完成，让流程自动执行到上一步
            context.success();
            return;
        }
    }
    
    // 原有业务逻辑...
}

2. 在FTL模板中添加回退按钮 #

在对应步骤的模板里，添加回退按钮，确保表单提交时带上回退参数，同时保留Keycloak的会话隐藏字段：

<form action="${url.loginAction}" method="post">
    ${auth.formData} <!-- 必须保留，维持会话完整性 -->
    
    <!-- 页面原有内容 -->
    
    <div class="form-group">
        <button type="submit" name="action" value="back" class="btn btn-secondary">返回上一步</button>
    </div>
</form>

3. 避免会话异常的关键注意事项 #

• 不要修改会话核心数据：回退操作仅调整Execution的状态，不要随意修改AuthenticationSession中的user、client等核心属性，避免认证上下文不一致。
• 保留用户输入数据：回退到上一步时，不要清除用户之前输入的信息（比如第一步的用户名），可以通过authSession.setAuthNote()存储临时数据，在回退后的步骤中回显。
• 禁用错误终止方法：不要调用context.cancel()或context.failure()，这些方法会直接终止整个认证流程，不符合回退需求。
• 兼容重复执行：确保每个自定义Authenticator在回退后重新执行时，能正确处理已有的会话数据，比如第一步的Authenticator可以从authSession中读取之前的用户名并回显在登录框中。

4. 验证流程正确性 #

• 测试每一步之间的回退操作，检查Keycloak后台的认证会话状态（可通过Admin Console的Sessions查看）。
• 验证回退后重新执行上一步时，用户输入的数据是否保留，认证逻辑是否正常触发。
• 排查是否出现InvalidSessionException等异常，确保回退操作不会导致会话失效。

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