Keycloak 21结合React实现登录后邮箱OTP验证码验证方案咨询

一、Keycloak服务端配置 #

1. 创建自定义认证流程 #

• 登录Keycloak管理控制台，进入admin_console_realm
• 导航到Authentication > Flows页面
• 找到默认的Browser流程，点击右侧Copy按钮，命名为Browser + Email OTP
• 展开新流程的Browser - Forms节点，点击Add execution，选择Email OTP并添加
• 将Email OTP的执行要求设置为REQUIRED，确保它在Password执行步骤之后（可拖拽调整顺序）
• 保存流程配置

2. 绑定客户端到新流程 #

• 进入Clients > admin_console_client页面
• 切换到Authentication Flow Overrides标签页
• 将Browser Flow设置为刚创建的Browser + Email OTP
• 若需要支持Postman用的密码授权模式（grant_type=password），重复以下操作：
  • 回到Authentication > Flows，复制默认Direct Grant流程，命名为Direct Grant + Email OTP
  • 展开流程，在Direct Grant - Validate Password后添加Email OTP执行并设为REQUIRED
  • 回到客户端的Authentication Flow Overrides，将Direct Grant Flow设置为这个新流程

3. 配置邮箱发送功能 #

• 导航到Realm Settings > Email页面
• 填写SMTP服务器信息（主机、端口、认证用户名/密码、发件人邮箱等）
• 点击Test Connection验证邮件配置是否正常，确保Keycloak能发送验证码邮件

二、React前端适配 #

• 保持现有keycloak-js集成逻辑不变，Keycloak会自动处理二次验证流程：
  • 用户输入用户名密码提交后，Keycloak会触发邮箱验证码发送，并在登录页面显示验证码输入框
  • 用户输入正确验证码后，自动完成认证并获取令牌

三、密码模式（Postman测试）的二次验证流程 #

1. 首次发送密码模式请求：

POST http://123.123.123.123:8080/realms/admin_console_realm/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

client_id=admin_console_client&grant_type=password&username=test&password=你的密码

2. 此时会返回错误响应，包含session_state和required_actions=["VERIFY_EMAIL_OTP"]
3. 携带验证码再次请求：

POST http://123.123.123.123:8080/realms/admin_console_realm/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

client_id=admin_console_client&grant_type=password&username=test&password=你的密码&session_state=获取到的会话状态&otp=邮箱收到的验证码

4. 验证通过后即可成功获取令牌

内容的提问来源于stack exchange，提问作者Peter Penzov