goalfylearning-admin/SSO_README.md

SSO 单点登录功能说明

概述

本项目已成功集成了单点登录（SSO）功能，参考了 goalfymax-backend 项目的实现。SSO功能支持OAuth2/OpenID Connect协议，提供完整的认证和授权流程。

功能特性

• OAuth2/OpenID Connect 支持: 完整的OAuth2授权码流程
• PKCE 安全增强: 使用PKCE（Proof Key for Code Exchange）增强安全性
• 令牌管理: 支持访问令牌和刷新令牌的管理
• 用户会话管理: 跟踪用户登录状态和在线用户
• 批量操作: 支持批量用户登出等管理功能

API 接口

1. SSO 登录初始化

POST /api/sso/login
Content-Type: application/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 回调处理

POST /api/sso/callback
Content-Type: application/json

{
  "code": "authorization_code",
  "state": "state_1234567890"
}

响应示例:

{
  "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. 刷新令牌

POST /api/sso/refresh
Content-Type: application/json

{
  "refresh_token": "your_refresh_token"
}

4. 用户登出

POST /api/sso/logout
Authorization: Bearer your_access_token

5. 获取用户信息

GET /api/sso/userinfo
Authorization: Bearer your_access_token

6. 获取在线用户列表

GET /api/sso/online-users

7. 获取在线用户数量

GET /api/sso/online-count

8. 批量用户登出

POST /api/sso/batch-logout
Content-Type: application/json

{
  "user_ids": [1, 2, 3]
}

配置说明

在 etc/config.yaml 中配置SSO相关参数：

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)

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)

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功能：

./test_sso_api.sh

注意事项

1. 确保SSO服务器正常运行并可访问
2. 配置正确的回调URI和客户端凭据
3. 定期清理过期的PKCE状态记录
4. 监控用户登录状态和异常情况

扩展功能

• 支持多种认证方式（密码、短信、邮箱等）
• 集成第三方身份提供商（Google、GitHub等）
• 实现单点登出（SLO）
• 添加多因素认证（MFA）
• 实现细粒度权限控制