Keycloak 26.5.1多MFA流配置异常：SMS/Email无法正常工作求助

通用流程基础检查 #

• 确认MFA父流模式：你需要用Alternative模式（而非Required），因为用户仅需匹配一种MFA方式。同时确保三个条件子流的条件是互斥的（用户属性mfa_option只会是单一值），避免多子流同时触发冲突。
• 检查子流类型：每个对应SMS/Email/TOTP的子流必须是Condition类型，且内部执行器为对应MFA验证组件，不要混用其他类型子流。
• 确认流程阶段：MFA子流必须放在Forms阶段之后（即用户名密码验证通过后触发），若前置会导致流程逻辑混乱。

分场景问题排查 #

SMS验证：登录页面刷新重启 #

• 检查SMS执行器配置：确认SMS服务商（如Twilio）的API密钥、发送号码等参数正确，查看standalone/log/server.log是否有API调用失败、权限不足的报错。
• 核对条件配置：条件规则需为User Attribute，属性名mfa_option，值SMS，匹配方式Equals，不要勾选"Negate"（反向匹配会导致逻辑错误）。
• 验证用户属性：确保用户已设置phoneNumber属性，格式需符合服务商要求（如带国家码），缺失或格式错误会导致流程异常跳转。

Email验证：抛出"Cannot login, credential setup required" #

• 检查执行器模式：使用OTP via Email执行器时，需配置为**"Send OTP"动态发送模式**，而非"Verify Existing Credential"（该模式要求用户预先设置过Email凭据，未设置则触发错误）。
• 确认用户邮箱属性：用户必须填写有效的email属性，同时检查Keycloak SMTP服务器配置（地址、端口、账号密码），查看日志是否有邮件发送失败记录。
• 移除跳过条件：若Email子流设置了"Skip if credential exists"，会导致未设置过Email凭据的用户直接触发错误，需取消该配置。

MFA挑战被直接跳过 #

• 校验用户属性准确性：确保mfa_option值无大小写或拼写错误（Keycloak属性匹配默认大小写敏感），比如用户属性是sms但配置条件是SMS会导致匹配失败。
• 检查子流状态：确认三个条件子流均为Enabled状态，未被意外禁用。
• 排查会话干扰：强制注销用户所有会话（Keycloak后台→用户→会话→注销），再用无痕模式测试，避免旧会话残留影响流程判断。

进阶调试步骤 #

• 开启调试日志：修改standalone.xml，将org.keycloak.authentication的日志级别设为DEBUG，重启后测试登录，通过日志追踪流程执行步骤，确认条件匹配、子流触发的具体节点。
• 单流隔离测试：暂时禁用另外两个MFA子流，仅保留一个（如先测试SMS），逐步排查是单一流配置问题还是多流共存的冲突。
• 版本兼容性检查：查看Keycloak官方版本bug列表，确认26.5.1是否存在已知的MFA流程异常问题。

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