Keycloak如何实现手机号+OTP的Direct Grant REST API登录

Keycloak原生支持这类Direct Grant（REST API直连授权）场景的自定义OTP认证逻辑，不需要修改核心源码，通过官方开放的SPI扩展点即可实现，完全匹配你现有的手机号+OTP两阶段交互逻辑，和已经落地的两类密码登录能力也不会产生冲突。

你提到的「仅能配置浏览器流程认证规则」是对Keycloak能力的常见认知偏差：内置的Direct Grant（即ROPC密码模式）确实默认只绑定了固定的用户名密码校验，但它开放了完整的自定义授权类型扩展能力，不需要强行把浏览器流程的认证逻辑套到API调用场景。

• 实现自定义otp授权类型SPI
  直接实现Keycloak提供的org.keycloak.protocol.oidc.grants.OAuth2GrantType接口，将授权类型标识设为otp，和你原有系统的grant_type参数值完全对齐，不需要改动原有password授权类型的逻辑：
  1. 两阶段逻辑直接对齐你原有业务规则：
     • 发码阶段：当接口请求仅携带手机号参数时，校验手机号对应用户存在后，生成6位OTP验证码与对应关联密钥，将密钥、用户ID、OTP值、过期时间存入Keycloak自带的SingleUseObjectProvider（单用途码存储，支持集群部署、自动过期），调用短信通道下发OTP后，直接返回{"otp_key": "生成的关联密钥", "expires_in": 300}给前端，这一步不生成访问令牌
     • 校验发令牌阶段：当接口请求携带otp_key和用户输入的otp_code参数时，先根据otp_key从单用途码存储中取出关联数据，校验OTP是否匹配、是否过期、是否已被使用，校验通过后直接复用Keycloak内置的令牌生成逻辑，返回和密码登录格式完全一致的access_token、refresh_token即可
  2. 按照SPI规范在META-INF/services目录下注册实现类，将打包后的jar包放到Keycloak的providers目录，执行kc.sh build后重启，即可在对应Realm的客户端配置中，为需要的客户端开启otp授权类型的调用权限。
• 复用现有能力减少开发量
  你之前实现用户名/密码、手机号/密码登录时已经写过的手机号匹配用户逻辑、用户状态校验逻辑、令牌生成逻辑，都可以直接在自定义otp授权类型中复用，不需要重复开发。
• 可选增强逻辑
  如果需要给OTP登录加风控拦截、频次限制、异地登录校验等规则，直接在自定义授权类型的逻辑中嵌入对应校验代码即可，比浏览器可视化配置的流程更灵活，完全适配纯API调用的场景，不会出现浏览器重定向之类不符合API交互预期的行为。

不要采用网上部分旧教程提到的「修改Direct Grant绑定的认证流程、追加OTP执行器」的方案：这类方案是把浏览器场景的一次性表单校验逻辑硬套到API场景，只能支持单请求完成所有校验的模式，无法实现你需要的「先发码返回密钥、前端二次提交校验」的两阶段交互，改造成本高还容易出现兼容问题。

内容的提问来源于stack exchange，提问作者Abdullah Memon