# 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）
- 实现细粒度权限控制