本文介绍开源项目 KeycloakQRLogin，目标为在 Keycloak 认证流程中实现 QR 扫码登录能力，适用于移动端已登录场景下的 Web 无密码快速登录。
项目地址：
https://github.com/huiyiruciduojiao/KeycloakQRLogin
该插件在 Keycloak 标准认证流程基础上扩展二维码会话机制、扫码确认接口及前端登录主题适配，为 Web 与移动端提供安全、规范的扫码登录通道。
项目目标
提供一套可在 Keycloak 环境内直接集成的二维码登录能力，满足以下需求：
- Web 登录页面支持二维码模式
- 移动端 App 扫码 + 确认完成登录
- 不依赖 Keycloak 外部网关或侵入业务后端
- 保持标准 OIDC/OAuth2 登录行为
- 可扩展、可维护、适合生产环境拓展
核心设计
1. 登录流程
| 阶段 | 描述 |
|---|---|
| 1 | Web 请求二维码登录，服务端生成 QR Session |
| 2 | 前端展示二维码 + 轮询登录状态 |
| 3 | App 扫码并提交验证请求（携带 Token） |
| 4 | 用户在 App 上确认登录 |
| 5 | Web 轮询状态变更，跳转完成 Keycloak 登录 |
采用“二维码 Session + 授权确认”双状态机制，避免伪造扫描 / 未确认登录行为。
2. 模块组成
| 模块 | 说明 |
|---|---|
| IdentityProvider IDP | 注册 QR 登录方式 |
| REST 端点 | 扫描确认接口 /scan, /confirm, /status |
| SessionStore | 维护二维码状态（内存/Redis） |
| 签名校验 | HMAC + 时间戳，避免伪请求与重放 |
| 登录主题扩展 | 注入二维码显示与轮询逻辑 |
3. 安全机制
| 机制 | 作用 |
|---|---|
| HMAC 签名 | 防篡改、来源校验 |
| 时间戳窗口 | 防重放攻击 |
| 会话 TTL | 二维码时效控制 |
| 双会话绑定 | QR Session + KC Session |
| Token 校验 | 扫码端用户真实身份验证 |
设计目标是遵循 Keycloak 的安全模型，避免额外攻击面。
配置说明
主要配置项：
| 配置项 | 说明 | 默认值 |
|---|---|---|
| Client Id | Token验证客户端ID | 无，必填项 |
| Clinet Secret | Token验证客户端密钥 | 无，必填项 |
| Session TTL (s) | 二维码会话有效期(秒) | 120 |
| Poll Interval (ms) | 前端轮询间隔(毫秒) | 1500 |
| Store Type | 存储类型(redis或memory) | memory |
| Redis URI | Redis连接地址 | redis://127.0.0.1:6379 |
| Redis Namespace | Redis键前缀 | qrlogin: |
| HMAC Secret | 签名校验密钥 | change-me |
| Algorithm | 签名算法 | HmacSHA256 |
| Time Window Seconds | 请求有效时间范围(秒) | 5 |
注：Redis 存储支持正在开发中，当前版本建议使用 memory 模式测试与调试，不建议直接用于生产分布式场景。
部署说明
构建与安装
mvn clean package
cp target/keycloak-qr-login-*.jar $KEYCLOAK_HOME/providers/
重启 Keycloak 后，通过管理控制台添加 QR Login 身份提供商，并配置登录主题引入二维码脚本。
兼容性
| 组件 | 要求 |
|---|---|
| Keycloak | 20+ |
| JDK | 17+ |
功能边界
当前实现范围
- Web 侧扫码登录流程
- 移动端 Token 验证 + 确认
- HMAC 安全协议
- Keycloak 前端主题接入
总结
KeycloakQRLogin 提供一种简洁、可扩展的二维码登录实现方式，通过 Keycloak SPI 与主题机制完成端到端能力扩展，同时保持 OAuth2 / OIDC 行为一致性。
适合以下场景：
- 移动端 + Web SSO
- 管理后台无密码登录
- 内网系统扫码登录
- 统一身份平台能力扩展
