mirror of
https://github.com/huiyiruciduojiao/KeycloakQRLogin.git
synced 2026-01-28 11:34:38 +08:00
3a41e0e7f5
- 创建项目概述和主要特性说明 - 添加技术架构和数据流图描述- 提供详细的配置项说明和默认值 - 编写安装部署步骤和环境要求 - 添加API接口说明和主要端点 - 补充开发指南和项目结构说明- 增加安全说明和特殊注意事项 - 添加许可证和联系信息
129 lines
3.7 KiB
Markdown
129 lines
3.7 KiB
Markdown
# 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. 构建项目:
|
||
``` bash
|
||
mvn clean package
|
||
```
|
||
2. 将生成的JAR包复制到Keycloak的providers目录:
|
||
```bash
|
||
cp target/keycloak-qr-login-*.jar $KEYCLOAK_HOME/providers/
|
||
```
|
||
3. 重启Keycloak服务
|
||
|
||
4. 在Keycloak管理界面中配置QR Login身份提供商
|
||
|
||
## API 接口
|
||
|
||
详细API文档请参考 [OpenAPI 文档](src/main/resources/openapi/qrlogin-openapi.yaml)
|
||
|
||
主要接口:
|
||
- 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
|
||
|