198 lines
4.7 KiB
Markdown
198 lines
4.7 KiB
Markdown
# 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）
|
||
- 实现细粒度权限控制
|