Keycloak QR Login

易识IT 开发的基于二维码的 Keycloak 登录插件。

项目概述

本项目是一个 Keycloak 身份提供商（Identity Provider）插件，实现了基于二维码的登录功能。用户可以通过扫描二维码，在移动设备上确认登录，实现更便捷、安全的身份验证。

主要特性：

• 支持二维码生成和展示
• 支持扫码状态轮询
• 支持基于JWT Token的身份验证
• 支持内存和Redis两种会话存储方式
• 完整的签名验证机制保证通信安全
• 可配置的各项参数

技术架构

主要组件

1. QRLoginIdentityProvider: 核心身份提供商实现
2. QRLoginEndpoint: REST API端点，处理扫码、确认等操作
3. SessionStore: 会话存储接口及实现（内存/Redis）
4. SignatureUtil: 签名工具，保障通信安全
5. 前端脚本: 实现二维码展示和状态轮询

数据流

1. 用户访问登录页面 -> 2. 点击"二维码登录" -> 3. 生成二维码并展示
   ↓
4. 用户使用App扫描二维码 <- 5. App调用/qr/scan接口
   ↓
6. 用户在App确认登录 -> 7. App调用/qr/confirm接口
   ↓
8. 前端轮询/qr/status获取状态 -> 9. 跳转到确认后的回调URL完成登录

配置说明

插件配置项

配置项	说明	默认值
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

环境要求

• Keycloak 20+
• Java 17+
• Redis (可选，用于分布式部署)

安装部署

1. 构建项目:

    mvn clean package
   

2. 将生成的JAR包复制到Keycloak的providers目录:

    cp target/keycloak-qr-login-*.jar $KEYCLOAK_HOME/providers/
   

3. 重启Keycloak服务

4. 在Keycloak管理界面中配置QR Login身份提供商

API 接口

详细API文档请参考 OpenAPI 文档

主要接口:

• POST /qr/scan: 处理二维码扫描
• POST /qr/confirm: 处理登录确认
• GET /qr/status: 查询二维码状态

开发指南

项目结构

src/main/java/top/ysit/qrlogin
├── config                 # 配置类
├── core                   # 核心组件
│   ├── security           # 安全相关
│   ├── store              # 会话存储
│   └── util               # 工具类
├── idp                    # 身份提供商实现
│   ├── resource           # REST资源
│   │   ├── endpoint       # 端点实现
│   │   └── factory        # 工厂类
│   └── QRLoginIdentityProvider*
└── spi                    # SPI实现

扩展功能

1. 添加新的存储实现: core\SessionStore.java 接口
2. 自定义签名算法: 扩展 SignatureConfig.SignatureAlgorithm
3. 修改前端样式: 编辑主题文件 theme/qrlogin/login/resources/js/script.js

安全说明

1. 所有API调用均需签名验证
2. 时间戳验证防止重放攻击
3. JWT Token验证确保用户身份合法性
4. 会话具有固定有效期，防止长期有效攻击

特殊说明

1. Redis功能暂时没有开发完整，待完善。
2. 基于IDP ISP 实现的，所以用户第一次登录时，需要绑定账号
3. 前端登录效果需要依赖theme/qrlogin/login/resources/js/script.js文件

许可证

Apache License 2.0

联系我们

易识IT