feat():learning后台管理项目初始化
This commit is contained in:
yuj
197
SSO_README.md
Normal file
197
SSO_README.md
Normal file
@@ -0,0 +1,197 @@
|
||||
# SSO 单点登录功能说明
|
||||
|
||||
## 概述
|
||||
|
||||
本项目已成功集成了单点登录（SSO）功能，参考了 `goalfymax-backend` 项目的实现。SSO功能支持OAuth2/OpenID Connect协议，提供完整的认证和授权流程。
|
||||
|
||||
## 功能特性
|
||||
|
||||
- **OAuth2/OpenID Connect 支持**: 完整的OAuth2授权码流程
|
||||
- **PKCE 安全增强**: 使用PKCE（Proof Key for Code Exchange）增强安全性
|
||||
- **令牌管理**: 支持访问令牌和刷新令牌的管理
|
||||
- **用户会话管理**: 跟踪用户登录状态和在线用户
|
||||
- **批量操作**: 支持批量用户登出等管理功能
|
||||
|
||||
## API 接口
|
||||
|
||||
### 1. SSO 登录初始化
|
||||
```http
|
||||
POST /api/sso/login
|
||||
Content-Type: application/json
|
||||
|
||||
{}
|
||||
```
|
||||
|
||||
**响应示例:**
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "操作成功",
|
||||
"data": {
|
||||
"success": true,
|
||||
"message": "SSO login initiated",
|
||||
"auth_url": "http://sso-server/oauth2/authorize?...",
|
||||
"state": "state_1234567890",
|
||||
"code_verifier": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. SSO 回调处理
|
||||
```http
|
||||
POST /api/sso/callback
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"code": "authorization_code",
|
||||
"state": "state_1234567890"
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例:**
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "操作成功",
|
||||
"data": {
|
||||
"success": true,
|
||||
"message": "SSO login successful",
|
||||
"access_token": "eyJhbGciOiJSUzI1NiIs...",
|
||||
"id_token": "eyJhbGciOiJSUzI1NiIs...",
|
||||
"refresh_token": "refresh_token_here",
|
||||
"expires_in": 3600,
|
||||
"user_info": {
|
||||
"sub": "123",
|
||||
"name": "John Doe",
|
||||
"email": "john@example.com"
|
||||
},
|
||||
"uuid": "unique-session-id"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 刷新令牌
|
||||
```http
|
||||
POST /api/sso/refresh
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"refresh_token": "your_refresh_token"
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 用户登出
|
||||
```http
|
||||
POST /api/sso/logout
|
||||
Authorization: Bearer your_access_token
|
||||
```
|
||||
|
||||
### 5. 获取用户信息
|
||||
```http
|
||||
GET /api/sso/userinfo
|
||||
Authorization: Bearer your_access_token
|
||||
```
|
||||
|
||||
### 6. 获取在线用户列表
|
||||
```http
|
||||
GET /api/sso/online-users
|
||||
```
|
||||
|
||||
### 7. 获取在线用户数量
|
||||
```http
|
||||
GET /api/sso/online-count
|
||||
```
|
||||
|
||||
### 8. 批量用户登出
|
||||
```http
|
||||
POST /api/sso/batch-logout
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"user_ids": [1, 2, 3]
|
||||
}
|
||||
```
|
||||
|
||||
## 配置说明
|
||||
|
||||
在 `etc/config.yaml` 中配置SSO相关参数：
|
||||
|
||||
```yaml
|
||||
sso:
|
||||
sso_server_url: "http://localhost:8080" # SSO服务器地址
|
||||
client_id: "admin-client" # OAuth客户端ID
|
||||
client_secret: "admin-secret" # OAuth客户端密钥
|
||||
redirect_uri: "http://localhost:8084/api/sso/callback" # 回调URI
|
||||
scope: "openid profile email" # 请求的作用域
|
||||
resource_aud: "admin-api" # 资源受众
|
||||
timeout: 30s # 请求超时时间
|
||||
```
|
||||
|
||||
## 数据库表结构
|
||||
|
||||
### PKCE状态表 (admin_pkce_states)
|
||||
```sql
|
||||
CREATE TABLE admin_pkce_states (
|
||||
id BIGINT PRIMARY KEY AUTO_INCREMENT,
|
||||
state VARCHAR(255) UNIQUE NOT NULL,
|
||||
code_verifier TEXT NOT NULL,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||||
deleted_at TIMESTAMP NULL
|
||||
);
|
||||
```
|
||||
|
||||
### 登录信息表 (admin_login_infos)
|
||||
```sql
|
||||
CREATE TABLE admin_login_infos (
|
||||
id BIGINT PRIMARY KEY AUTO_INCREMENT,
|
||||
user_id INT NOT NULL,
|
||||
user_name VARCHAR(100) NOT NULL,
|
||||
email VARCHAR(255) NOT NULL,
|
||||
uuid VARCHAR(100) NOT NULL,
|
||||
is_online BOOLEAN DEFAULT FALSE,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||||
deleted_at TIMESTAMP NULL
|
||||
);
|
||||
```
|
||||
|
||||
## 安全特性
|
||||
|
||||
1. **PKCE 保护**: 使用PKCE增强OAuth2安全性，防止授权码拦截攻击
|
||||
2. **状态验证**: 使用state参数防止CSRF攻击
|
||||
3. **令牌验证**: 通过SSO服务器验证令牌有效性
|
||||
4. **会话管理**: 跟踪用户登录状态，支持强制登出
|
||||
|
||||
## 使用流程
|
||||
|
||||
1. **前端发起登录**: 调用 `/api/sso/login` 获取授权URL
|
||||
2. **用户授权**: 用户跳转到SSO服务器进行授权
|
||||
3. **处理回调**: SSO服务器回调到 `/api/sso/callback`
|
||||
4. **获取令牌**: 系统自动交换授权码获取访问令牌
|
||||
5. **用户认证**: 使用访问令牌调用需要认证的API
|
||||
6. **令牌刷新**: 使用刷新令牌获取新的访问令牌
|
||||
7. **用户登出**: 调用 `/api/sso/logout` 结束会话
|
||||
|
||||
## 测试
|
||||
|
||||
使用提供的测试脚本验证SSO功能：
|
||||
|
||||
```bash
|
||||
./test_sso_api.sh
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. 确保SSO服务器正常运行并可访问
|
||||
2. 配置正确的回调URI和客户端凭据
|
||||
3. 定期清理过期的PKCE状态记录
|
||||
4. 监控用户登录状态和异常情况
|
||||
|
||||
## 扩展功能
|
||||
|
||||
- 支持多种认证方式（密码、短信、邮箱等）
|
||||
- 集成第三方身份提供商（Google、GitHub等）
|
||||
- 实现单点登出（SLO）
|
||||
- 添加多因素认证（MFA）
|
||||
- 实现细粒度权限控制
|
||||
Reference in New Issue
Block a user