PANDA-JSR/SecScore
1
0
Fork 0
mirror of https://github.com/SECTL/SecScore.git synced 2026-07-19 19:04:23 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add OAuth 2.0 authorization flow documentation and troubleshooting guide

Browse Source 
- Created AUTH/OAUTH_FLOW.MD to detail the OAuth 2.0 authorization process for SECTL Auth, including flow diagrams, detailed steps, token management, and security recommendations.
- Added AUTH/TROUBLESHOOTING.md to provide a comprehensive troubleshooting guide for common issues encountered during the OAuth process, covering authorization, token exchange, user info retrieval, remote logout, platform management, and network/CORS issues.
- Implemented OAuthCallback and OAuthLogin components in React to handle OAuth login flow, including deep linking and token exchange.
This commit is contained in:
NanGua-QWQ
2026-03-30 19:15:57 +08:00
parent 9c3e84d912
commit 9f2bf644b5
7 changed files with 2424 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.eslintcache
+1
View File
File diff suppressed because one or more lines are too long
AUTH/API.MD
+922
View File
@@ -0,0 +1,922 @@
# SECTL Auth API 参考
本文档详细说明 SECTL Auth 提供的所有 API 接口。
## 基础信息
- **基础 URL**: `https://sectl.top`
- **认证方式**: OAuth 2.0 + Bearer Token
- **数据格式**: JSON
## 接口概览
| 接口 | 方法 | 说明 | 对应页面 |
| ----------------------- | ---- | ------------------- | ------------------------ |
| `/oauth/authorize` | GET | 获取授权码 | OAuthAuthorizeView.vue |
| `/api/oauth/token` | POST | 换取/刷新令牌 | AuthCallbackView.vue |
| `/api/oauth/userinfo` | GET | 获取用户信息 | PlatformUsersView.vue |
| `/api/oauth/config` | POST | 配置 Token 过期时间 | PlatformSettingsView.vue |
| `/api/oauth/revoke` | POST | 撤销令牌 | SecurityView.vue |
| `/api/oauth/introspect` | POST | 验证令牌 | - |
---
## OAuth 接口
### 1. 获取授权码
引导用户跳转到授权页面。
```http
GET /oauth/authorize
```
**请求参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------------- | ------ | ---- | ---------------- |
| client_id | string | ✅ | 平台 ID |
| redirect_uri | string | ✅ | 回调 URL |
| response_type | string | ✅ | 固定值 `code` |
| state | string | ❌ | 防 CSRF 状态参数 |
**示例请求：**
```
https://sectl.top/oauth/authorize?client_id=pf_AHmIhAiptyLFxk8x&redirect_uri=http://localhost:5000/callback&response_type=code
```
**成功响应：**
- 重定向到 `redirect_uri?code={authorization_code}&state={state}`
**错误响应：**
- 重定向到 `redirect_uri?error={error_code}&error_description={description}`
**错误码：**
| 错误码 | 说明 |
| ------------------------- | ------------------ |
| invalid_request | 请求参数缺失或无效 |
| unauthorized_client | 客户端未授权 |
| access_denied | 用户拒绝授权 |
| unsupported_response_type | 不支持的响应类型 |
| invalid_scope | 无效的权限范围 |
| server_error | 服务器内部错误 |
**相关页面：**
- [OAuthAuthorizeView.vue](../../src/views/OAuthAuthorizeView.vue) - 授权页面
- [LoginView.vue](../../src/views/LoginView.vue) - 登录页面
---
### 2. 获取访问令牌
使用授权码换取访问令牌。
```http
POST /api/oauth/token
```
**请求头：**
```
Content-Type: application/json
```
**请求体：**
| 参数名 | 类型 | 必填 | 说明 |
| ------------- | ------ | ---- | ------------------------------------------------ |
| grant_type | string | ✅ | `authorization_code` 或 `refresh_token` |
| code | string | 条件 | 授权码（grant_type=authorization_code 时必填） |
| refresh_token | string | 条件 | 刷新令牌（grant_type=refresh_token 时必填） |
| client_id | string | ✅ | 平台 ID |
| client_secret | string | ✅ | 平台密钥 |
| redirect_uri | string | 条件 | 回调地址（grant_type=authorization_code 时必填） |
**授权码模式示例：**
```json
{
"grant_type": "authorization_code",
"code": "NjliNDIyOTYwMDE4znLUNeWM6J8ye0MC",
"client_id": "pf_AHmIhAiptyLFxk8x",
"client_secret": "sk_UyMHuFf6oKXh8ZcHSb7lfOSgzumoOeg1",
"redirect_uri": "http://localhost:5000/callback"
}
```
**刷新令牌模式示例：**
```json
{
"grant_type": "refresh_token",
"refresh_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"client_id": "pf_AHmIhAiptyLFxk8x",
"client_secret": "sk_UyMHuFf6oKXh8ZcHSb7lfOSgzumoOeg1"
}
```
**成功响应：**
```json
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"token_type": "Bearer",
"expires_in": 3600
}
```
**响应字段：**
| 字段 | 类型 | 说明 |
| ------------- | ------ | ----------------------- |
| access_token | string | 访问令牌（JWT） |
| refresh_token | string | 刷新令牌 |
| token_type | string | 令牌类型，固定为 Bearer |
| expires_in | number | 过期时间（秒） |
**错误响应：**
```json
{
"error": "invalid_grant",
"error_description": "Authorization code has expired"
}
```
**错误码：**
| 错误码 | HTTP 状态 | 说明 |
| ---------------------- | --------- | ------------------------ |
| invalid_request | 400 | 请求格式错误 |
| invalid_client | 401 | 客户端认证失败 |
| invalid_grant | 400 | 授权码无效或过期 |
| unauthorized_client | 400 | 客户端无权使用此授权类型 |
| unsupported_grant_type | 400 | 不支持的授权类型 |
| invalid_scope | 400 | 无效的权限范围 |
**相关页面：**
- [AuthCallbackView.vue](../../src/views/AuthCallbackView.vue) - 回调处理
---
### 3. 获取用户信息
使用访问令牌获取用户信息。
```http
GET /api/oauth/userinfo
```
**请求头：**
```
Authorization: Bearer {access_token}
```
**成功响应：**
```json
{
"user_id": "69bd422960018cf4d0e5",
"email": "user@example.com",
"name": "张三",
"github_username": "zhangsan",
"permission": 1
}
```
**响应字段：**
| 字段 | 类型 | 说明 |
| --------------- | ------ | --------------------- |
| user_id | string | 用户唯一标识 |
| email | string | 用户邮箱 |
| name | string | 用户名称 |
| github_username | string | GitHub 用户名（如有） |
| permission | number | 用户权限等级 |
**错误响应：**
```json
{
"error": "invalid_token",
"error_description": "The access token is invalid or has expired"
}
```
**相关页面：**
- [PlatformUsersView.vue](../../src/views/dashboard/manage/PlatformUsersView.vue) - 平台用户列表
---
### 4. 配置 Token 过期时间
配置平台的 access_token 过期时间（需要管理员权限）。
```http
POST /api/oauth/config
```
**请求头：**
```
Content-Type: application/json
```
**请求体：**
| 参数名 | 类型 | 必填 | 说明 |
| ------------ | ------ | ---- | ------------------------------------------- |
| platform_id | string | ✅ | 平台 ID |
| expires_in | number | ✅ | 过期时间（秒），-1 表示永不过期，最小 60 秒 |
| admin_secret | string | ✅ | 管理员密钥 |
**请求示例：**
```json
{
"platform_id": "pf_AHmIhAiptyLFxk8x",
"expires_in": 86400,
"admin_secret": "your-admin-secret"
}
```
**成功响应：**
```json
{
"success": true,
"message": "Token expiration time updated",
"expires_in": 86400
}
```
**错误响应：**
```json
{
"error": "unauthorized",
"error_description": "Invalid admin secret"
}
```
**相关页面：**
- [PlatformSettingsView.vue](../../src/views/dashboard/other/PlatformSettingsView.vue) - 平台设置
---
### 5. 撤销令牌
撤销指定的访问令牌或刷新令牌。
```http
POST /api/oauth/revoke
```
**请求头：**
```
Content-Type: application/json
```
**请求体：**
| 参数名 | 类型 | 必填 | 说明 |
| --------------- | ------ | ---- | --------------------------------- |
| token | string | ✅ | 要撤销的令牌 |
| token_type_hint | string | ❌ | `access_token` 或 `refresh_token` |
| client_id | string | ✅ | 平台 ID |
| client_secret | string | ✅ | 平台密钥 |
**请求示例：**
```json
{
"token": "eyJhbGciOiJIUzI1NiIs...",
"token_type_hint": "access_token",
"client_id": "pf_AHmIhAiptyLFxk8x",
"client_secret": "sk_UyMHuFf6oKXh8ZcHSb7lfOSgzumoOeg1"
}
```
**成功响应：**
```json
{
"success": true,
"message": "Token revoked successfully"
}
```
**相关页面：**
- [SecurityView.vue](../../src/views/dashboard/other/SecurityView.vue) - 安全设置
- [LoginPlatformsView.vue](../../src/views/dashboard/list/LoginPlatformsView.vue) - 登录平台列表
---
### 6. 验证令牌
验证访问令牌的有效性和获取令牌信息。
```http
POST /api/oauth/introspect
```
**请求头：**
```
Content-Type: application/json
```
**请求体：**
| 参数名 | 类型 | 必填 | 说明 |
| ------------- | ------ | ---- | ------------ |
| token | string | ✅ | 要验证的令牌 |
| client_id | string | ✅ | 平台 ID |
| client_secret | string | ✅ | 平台密钥 |
**请求示例：**
```json
{
"token": "eyJhbGciOiJIUzI1NiIs...",
"client_id": "pf_AHmIhAiptyLFxk8x",
"client_secret": "sk_UyMHuFf6oKXh8ZcHSb7lfOSgzumoOeg1"
}
```
**活跃令牌响应：**
```json
{
"active": true,
"user_id": "69bd422960018cf4d0e5",
"client_id": "pf_AHmIhAiptyLFxk8x",
"exp": 1704783600,
"iat": 1704780000
}
```
**非活跃令牌响应：**
```json
{
"active": false
}
```
**响应字段：**
| 字段 | 类型 | 说明 |
| --------- | ------- | ------------------------ |
| active | boolean | 令牌是否有效 |
| user_id | string | 用户 ID（仅活跃令牌） |
| client_id | string | 平台 ID（仅活跃令牌） |
| exp | number | 过期时间戳（仅活跃令牌） |
| iat | number | 签发时间戳（仅活跃令牌） |
---
## 平台管理 API
以下 API 用于管理平台信息，需要通过 Appwrite SDK 调用。
### 获取平台列表
```javascript
// 使用 Appwrite SDK
const result = await databases.listDocuments({
databaseId: "69bd89d8000304c37368",
collectionId: "platforms",
queries: [Query.orderDesc("$createdAt"), Query.limit(100)],
})
```
**相关页面：**
- [PlatformManagementView.vue](../../src/views/dashboard/manage/PlatformManagementView.vue)
### 获取平台详情
```javascript
const platform = await databases.getDocument({
databaseId: "69bd89d8000304c37368",
collectionId: "platforms",
documentId: "platform-document-id",
})
```
**相关页面：**
- [PlatformDetailView.vue](../../src/views/dashboard/detail/PlatformDetailView.vue)
### 更新平台信息
```javascript
await databases.updateDocument({
databaseId: "69bd89d8000304c37368",
collectionId: "platforms",
documentId: "platform-document-id",
data: {
callback_url: "http://new-callback.com",
token_expires_in: 7200,
},
})
```
**相关页面：**
- [PlatformSettingsView.vue](../../src/views/dashboard/other/PlatformSettingsView.vue)
### 申请创建平台
```javascript
await databases.createDocument({
databaseId: "69bd89d8000304c37368",
collectionId: "platform_applications",
documentId: ID.unique(),
data: {
name: "我的应用",
description: "应用描述",
callback_url: "http://localhost:5000/callback",
owner_id: currentUser.$id,
status: "pending",
created_at: new Date().toISOString(),
},
})
```
**相关页面：**
- [PlatformApplyView.vue](../../src/views/dashboard/form/PlatformApplyView.vue)
---
## 用户管理 API
### 获取用户授权的平台列表
```javascript
const result = await databases.listDocuments({
databaseId: "69bd89d8000304c37368",
collectionId: "oauth_tokens",
queries: [Query.equal("user_id", currentUser.$id), Query.equal("revoked", false)],
})
```
**相关页面：**
- [LoginPlatformsView.vue](../../src/views/dashboard/list/LoginPlatformsView.vue)
### 获取平台授权用户列表
```javascript
const result = await databases.listDocuments({
databaseId: "69bd89d8000304c37368",
collectionId: "oauth_tokens",
queries: [Query.equal("platform_id", "pf_xxx"), Query.equal("revoked", false)],
})
```
**相关页面：**
- [PlatformUsersView.vue](../../src/views/dashboard/manage/PlatformUsersView.vue)
---
## 云存储 API
云存储 API 提供文件上传、下载、管理等功能。需要通过 OAuth access_token 进行认证。
### 接口概览
| 接口 | 方法 | 说明 | SDK 方法 |
| ------------------------------- | ------ | ------------------------ | ------------------------------- |
| `/api/cloud/upload` | POST | 上传文件 | `uploadFile()` |
| `/api/cloud/files/{file_id}` | GET | 获取文件信息 | `getFile()` |
| `/api/cloud/download/{file_id}` | GET | 获取下载链接 | `downloadFile()` |
| `/api/cloud/view/{file_id}` | GET | 查看文件内容 | `viewFile()` |
| `/api/cloud/preview/{file_id}` | GET | 预览文件（支持图片处理） | `previewFile()` |
| `/api/cloud/info` | GET | 获取存储信息 | `getStorageInfo()` |
| `/api/cloud/files` | GET | 列出/搜索文件 | `listFiles()` / `searchFiles()` |
| `/api/cloud/files/{file_id}` | PUT | 更新文件（重命名） | `updateFile()` |
| `/api/cloud/files/{file_id}` | DELETE | 删除文件 | `deleteFile()` |
---
### 1. 上传文件
上传文件到云存储，系统会自动验证文件格式和检查存储容量。
```http
POST /api/cloud/upload
```
**请求头：**
```
Authorization: Bearer {access_token}
Content-Type: multipart/form-data
```
**请求参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ----------- | ------ | ---- | ------------ |
| file | File | ✅ | 要上传的文件 |
| platform_id | string | ✅ | 平台 ID |
**请求示例（JavaScript）：**
```javascript
const formData = new FormData()
formData.append("file", fileInput.files[0])
formData.append("platform_id", "pf_AHmIhAiptyLFxk8x")
const response = await fetch("https://sectl.top/api/cloud/upload", {
method: "POST",
headers: {
Authorization: "Bearer eyJhbGciOiJIUzI1NiIs...",
},
body: formData,
})
```
**成功响应：**
```json
{
"success": true,
"file_id": "cf_xxxxxxxx",
"filename": "example.jpg",
"size": 1024567,
"url": "https://cloud.appwrite.io/v1/storage/buckets/69c869010007b752a9b1/files/xxx/view",
"storage": {
"used": "50MB",
"limit": "100MB",
"available": "50MB",
"percentage": 50
}
}
```
**错误响应 - 格式不允许：**
```json
{
"error": "invalid_format",
"error_description": "File format 'exe' is not allowed",
"allowed_formats": ["jpg", "png", "pdf"]
}
```
**错误响应 - 超出容量：**
```json
{
"error": "storage_exceeded",
"error_description": "Upload would exceed storage limit",
"storage": {
"used": "95MB",
"limit": "100MB",
"available": "5MB",
"requested": "10MB"
}
}
```
**相关页面：**
- [CloudServiceView.vue](../../src/views/dashboard/CloudServiceView.vue) - 云服务总览
---
### 2. 下载文件
获取文件的下载链接。
```http
GET /api/cloud/download/{file_id}
```
**请求头：**
```
Authorization: Bearer {access_token}
```
**路径参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ------ | ---- | ------- |
| file_id | string | ✅ | 文件 ID |
**成功响应：**
```json
{
"success": true,
"file_id": "cf_xxxxxxxx",
"filename": "example.jpg",
"download_url": "https://cloud.appwrite.io/v1/storage/buckets/69c869010007b752a9b1/files/xxx/download",
"expires_at": "2025-01-01T01:00:00Z"
}
```
---
### 3. 获取存储信息
获取用户在该平台的存储使用情况和配置信息。
```http
GET /api/cloud/info?platform_id={platform_id}
```
**请求头：**
```
Authorization: Bearer {access_token}
```
**查询参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ----------- | ------ | ---- | ------- |
| platform_id | string | ✅ | 平台 ID |
**成功响应：**
```json
{
"success": true,
"platform_id": "pf_xxx",
"tier": "free",
"storage": {
"used": 52428800,
"used_formatted": "50MB",
"limit": 104857600,
"limit_formatted": "100MB",
"available": 52428800,
"available_formatted": "50MB",
"percentage": 50
},
"allowed_formats": ["jpg", "png", "pdf"],
"max_file_size": 10485760
}
```
---
### 4. 列出文件
获取用户在该平台的文件列表。
```http
GET /api/cloud/files?platform_id={platform_id}&limit=20&offset=0
```
**请求头：**
```
Authorization: Bearer {access_token}
```
**查询参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ----------- | ------ | ---- | ----------------- |
| platform_id | string | ✅ | 平台 ID |
| limit | number | ❌ | 每页数量，默认 20 |
| offset | number | ❌ | 偏移量，默认 0 |
**成功响应：**
```json
{
"success": true,
"files": [
{
"file_id": "cf_xxx",
"filename": "example.jpg",
"size": 1024567,
"size_formatted": "1MB",
"created_at": "2025-01-01T00:00:00Z"
}
],
"total": 10,
"limit": 20,
"offset": 0
}
```
---
### 5. 删除文件
删除指定的文件。
```http
DELETE /api/cloud/files/{file_id}
```
**请求头：**
```
Authorization: Bearer {access_token}
```
**路径参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ------ | ---- | ------- |
| file_id | string | ✅ | 文件 ID |
**成功响应：**
```json
{
"success": true,
"message": "File deleted successfully",
"storage": {
"used": "45MB",
"limit": "100MB",
"available": "55MB"
}
}
```
---
## 云存储 SDK
我们提供了 JavaScript SDK 简化云存储 API 的调用。
### 安装
```html
<script src="https://sectl.top/platform-sdk/cloud-storage.js"></script>
```
或使用 ES6 模块：
```javascript
import CloudStorage from "./cloud-storage.js"
```
### 初始化
```javascript
const cloud = new CloudStorage({
baseUrl: "https://sectl.top",
platformId: "your_platform_id",
accessToken: "your_access_token",
})
```
### 使用示例
```javascript
// 上传文件
try {
const result = await cloud.uploadFile(fileInput.files[0])
console.log("文件上传成功:", result.file_id)
console.log("存储使用情况:", result.storage.percentage + "%")
} catch (error) {
if (error.code === "invalid_format") {
console.error("不支持的文件格式:", error.data.allowed_formats)
} else if (error.code === "storage_exceeded") {
console.error("存储空间不足")
}
}
// 获取存储信息
const info = await cloud.getStorageInfo()
console.log("已用空间:", info.storage.used_formatted)
console.log("允许格式:", info.allowed_formats)
// 列出文件
const files = await cloud.listFiles({ limit: 10 })
files.files.forEach((file) => {
console.log(file.filename, file.size_formatted)
})
// 下载文件
const download = await cloud.downloadFile("cf_xxx")
window.location.href = download.download_url
// 删除文件
await cloud.deleteFile("cf_xxx")
```
**相关文件：**
- [cloud-storage.js](../../platform-sdk/cloud-storage.js) - SDK 源码
---
## 远程退登 API
### 创建退登事件
当用户退出登录时，系统会自动创建退登事件。
```javascript
await databases.createDocument({
databaseId: "69bd89d8000304c37368",
collectionId: "logout_events",
documentId: ID.unique(),
data: {
user_id: currentUser.$id,
platform_id: null, // null 表示全局退出
global: true,
created_at: new Date().toISOString(),
},
})
```
### 订阅退登事件
使用 Appwrite Realtime 订阅退登事件：
```javascript
import { Client } from "appwrite"
const client = new Client()
.setEndpoint("https://cloud.appwrite.io/v1")
.setProject("your-project-id")
const unsubscribe = client.subscribe(
"databases.69bd89d8000304c37368.collections.logout_events.documents",
(response) => {
const event = response.payload
if (event.user_id === currentUserId) {
// 执行本地退出
localLogout()
}
}
)
```
**相关页面：**
- [SecurityView.vue](../../src/views/dashboard/other/SecurityView.vue)
---
## 错误处理
### HTTP 状态码
| 状态码 | 说明 |
| ------ | ------------------ |
| 200 | 请求成功 |
| 400 | 请求参数错误 |
| 401 | 未授权，认证失败 |
| 403 | 禁止访问，权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
### 错误响应格式
```json
{
"error": "error_code",
"error_description": "详细的错误描述",
"error_uri": "https://docs.example.com/error/error_code"
}
```
---
## 安全建议
1. **使用 HTTPS** - 所有 API 通信必须使用 HTTPS
2. **保护密钥** - 不要在客户端代码中暴露 client_secret
3. **验证回调地址** - 确保 redirect_uri 与注册时一致
4. **使用状态参数** - 添加 state 参数防止 CSRF 攻击
5. **安全存储令牌** - Token 应安全存储，避免泄露
6. **及时撤销** - 用户退出时及时撤销令牌
---
## 相关页面
- [OAuthAuthorizeView.vue](../../src/views/OAuthAuthorizeView.vue) - OAuth 授权页面
- [AuthCallbackView.vue](../../src/views/AuthCallbackView.vue) - 认证回调
- [PlatformManagementView.vue](../../src/views/dashboard/manage/PlatformManagementView.vue) - 平台管理
- [PlatformDetailView.vue](../../src/views/dashboard/detail/PlatformDetailView.vue) - 平台详情
- [PlatformSettingsView.vue](../../src/views/dashboard/other/PlatformSettingsView.vue) - 平台设置
- [SecurityView.vue](../../src/views/dashboard/other/SecurityView.vue) - 安全设置
- [LoginPlatformsView.vue](../../src/views/dashboard/list/LoginPlatformsView.vue) - 登录平台列表
AUTH/AUTH.MD
+482
View File
@@ -0,0 +1,482 @@
# 平台接入指南
本文档介绍如何将第三方平台与 SECTL Auth 集成，实现统一认证和远程退登功能。
## 目录
- [概述](#概述)
- [快速开始](#快速开始)
- [管理后台功能](#管理后台功能)
- [OAuth 集成](#oauth-集成)
- [远程退登](#远程退登)
- [代码示例](#代码示例)
- [常见问题](#常见问题)
## 概述
SECTL Auth 提供以下核心功能：
1. **统一认证** - 用户使用 SECTL Auth 账号登录第三方平台
2. **远程退登** - 用户在 SECTL Auth 中心退出后，平台自动退出
3. **用户管理** - 查看已授权用户、统计信息等
### 工作流程
```
┌─────────────┐ 登录请求 ┌─────────────┐
│ 用户 │ ─────────────> │ SECTL Auth │
│ │ │ │
│ 平台A │ <───────────── │ 认证中心 │
│ │ Access Token │ │
└──────┬──────┘ └──────┬──────┘
│ │
│ 远程退登通知 │
│ <─────────────────────────── │
│ (Realtime) │
▼ ▼
自动退出登录 用户点击退出
```
## 快速开始
### 1. 注册平台
在 SECTL Auth 平台管理页面 ([PlatformManagementView.vue](../../src/views/dashboard/manage/PlatformManagementView.vue)) 申请接入，获取：
| 参数 | 说明 | 示例 |
| -------------- | ------------ | ------------------------------------- |
| platform_id | 平台唯一标识 | `pf_AHmIhAiptyLFxk8x` |
| platform_token | 平台认证密钥 | `sk_UyMHuFf6oKXh8ZcHSb7lfOSgzumoOeg1` |
| callback_url | 回调地址 | `http://localhost:5000/callback` |
### 2. 平台状态说明
平台在管理后台有以下状态：
| 状态 | 说明 | 可操作 |
| -------- | ------ | -------- |
| active | 运行中 | 正常授权 |
| pending | 审核中 | 等待审核 |
| disabled | 已停用 | 无法授权 |
### 3. 查看统计信息
在平台管理页面可以查看：
- **总平台数** - 已创建的平台数量
- **运行中** - 活跃平台数量
- **审核中** - 待审核申请数量
- **总用户数** - 授权用户总数
## 管理后台功能
### 平台列表 ([PlatformManagementView.vue](../../src/views/dashboard/manage/PlatformManagementView.vue))
平台管理页面提供以下功能：
#### 1. 平台卡片展示
每个平台显示：
- 平台名称和描述
- 状态标签（运行中/审核中/已停用）
- 创建时间
- 授权用户数
- 管理按钮
#### 2. 搜索和过滤
- 按名称搜索平台
- 按状态过滤
- 分页展示
#### 3. 快捷操作
- **新建平台** - 跳转到申请页面
- **我的申请** - 查看自己的平台申请
- **审核申请** - 审核其他用户的申请（需 >=18 权限）
### 平台详情 ([PlatformDetailView.vue](../../src/views/dashboard/detail/PlatformDetailView.vue))
查看平台详细信息：
#### 基本信息
- 平台 ID (Client ID)
- 平台密钥 (Client Secret)
- 回调地址
- 创建时间
#### 安全设置
- Token 过期时间配置
- 密钥重置
- 回调地址修改
#### 用户统计
- 授权用户列表
- 登录时间
- 最后活跃时间
### 平台申请 ([PlatformApplyView.vue](../../src/views/dashboard/form/PlatformApplyView.vue))
申请创建新平台：
```javascript
// 申请参数
{
name: "我的应用", // 平台名称
description: "应用描述", // 平台描述
callback_url: "http://..." // 回调地址
}
```
申请后状态为 `pending`，等待管理员审核。
### 申请审核 ([PlatformApplicationsView.vue](../../src/views/dashboard/manage/PlatformApplicationsView.vue))
管理员审核平台申请：
- 查看申请详情
- 批准申请（状态变为 `active`）
- 拒绝申请（状态变为 `disabled`）
## OAuth 集成
### 授权流程
#### 1. 引导用户到授权页面
```
GET https://sectl.top/oauth/authorize
```
**参数：**
| 参数名 | 必填 | 说明 |
| ------------- | ---- | ------------- |
| client_id | ✅ | 平台 ID |
| redirect_uri | ✅ | 回调地址 |
| response_type | ✅ | 固定值 `code` |
**示例：**
```
https://sectl.top/oauth/authorize?client_id=pf_xxx&redirect_uri=http://localhost:5000/callback&response_type=code
```
#### 2. 处理回调
用户授权后，会重定向到：
```
{callback_url}?code={authorization_code}
```
#### 3. 换取访问令牌
```http
POST https://sectl.top/api/oauth/token
Content-Type: application/json
{
"grant_type": "authorization_code",
"code": "授权码",
"client_id": "pf_xxx",
"client_secret": "sk_xxx",
"redirect_uri": "http://localhost:5000/callback"
}
```
**响应：**
```json
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"refresh_token": "xxx",
"token_type": "Bearer",
"expires_in": 3600
}
```
#### 4. 获取用户信息
```http
GET https://sectl.top/api/oauth/userinfo
Authorization: Bearer {access_token}
```
**响应：**
```json
{
"user_id": "69bd422960018cf4d0e5",
"email": "user@example.com",
"name": "张三",
"github_username": "zhangsan"
}
```
## 远程退登
### 实现原理
1. 用户在 SECTL Auth 点击退出登录
2. 系统创建 `logout_events` 文档
3. 第三方应用通过 Appwrite Realtime 订阅该集合
4. 收到匹配的事件后执行本地退出
### 集成步骤
#### 1. 安装 Appwrite SDK
**C#**
```bash
dotnet add package Appwrite
```
**Python**
```bash
pip install appwrite
```
#### 2. 配置 Realtime 订阅
**C# 示例：**
```csharp
using Appwrite;
using Appwrite.Services;
var client = new Client()
.SetEndpoint("https://cloud.appwrite.io/v1")
.SetProject("your-project-id");
var realtime = new Realtime(client);
// 订阅 logout_events 集合
realtime.Subscribe("databases.{databaseId}.collections.logout_events.documents",
callback: (message) => {
var logoutEvent = message.Payload;
if (logoutEvent.UserId == currentUserId) {
// 执行本地退出
LocalLogout();
}
});
```
**Python 示例：**
```python
from appwrite.client import Client
from appwrite.services.realtime import Realtime
client = Client()
client.set_endpoint('https://cloud.appwrite.io/v1')
client.set_project('your-project-id')
realtime = Realtime(client)
def on_logout_event(message):
event = message['payload']
if event['user_id'] == current_user_id:
# 执行本地退出
local_logout()
# 订阅 logout_events 集合
realtime.subscribe(
'databases.{database_id}.collections.logout_events.documents',
callback=on_logout_event
)
```
### 数据结构
**logout_events 集合字段：**
| 字段 | 类型 | 说明 |
| ----------- | ------- | ------------------ |
| user_id | String | 退出登录的用户ID |
| platform_id | String | 特定平台ID（可选） |
| global | Boolean | 是否全局退出 |
| created_at | String | 创建时间 |
## 代码示例
### C# 完整示例
详见 [csharp-example](./csharp-example/) 目录。
```csharp
// SectlAuthClient.cs
public class SectlAuthClient
{
private readonly string _platformId;
private readonly string _platformSecret;
private readonly string _callbackUrl;
private readonly HttpClient _httpClient;
public SectlAuthClient(string platformId, string platformSecret, string callbackUrl)
{
_platformId = platformId;
_platformSecret = platformSecret;
_callbackUrl = callbackUrl;
_httpClient = new HttpClient();
}
// 获取授权 URL
public string GetAuthorizationUrl()
{
return $"https://sectl.top/oauth/authorize?" +
$"client_id={_platformId}&" +
$"redirect_uri={Uri.EscapeDataString(_callbackUrl)}&" +
$"response_type=code";
}
// 换取访问令牌
public async Task<TokenResponse> ExchangeCodeAsync(string code)
{
var request = new
{
grant_type = "authorization_code",
code = code,
client_id = _platformId,
client_secret = _platformSecret,
redirect_uri = _callbackUrl
};
var response = await _httpClient.PostAsJsonAsync(
"https://sectl.top/api/oauth/token", request);
return await response.Content.ReadFromJsonAsync<TokenResponse>();
}
// 获取用户信息
public async Task<UserInfo> GetUserInfoAsync(string accessToken)
{
_httpClient.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", accessToken);
var response = await _httpClient.GetAsync(
"https://sectl.top/api/oauth/userinfo");
return await response.Content.ReadFromJsonAsync<UserInfo>();
}
}
```
### Python 完整示例
详见 [python-example](./python-example/) 目录。
```python
# sectl_auth/client.py
import requests
class SectlAuthClient:
BASE_URL = "https://sectl.top"
AUTH_URL = "https://sectl.top"
def __init__(self, platform_id: str, platform_secret: str, callback_url: str):
self.platform_id = platform_id
self.platform_secret = platform_secret
self.callback_url = callback_url
def get_authorization_url(self) -> str:
"""获取授权 URL"""
return (
f"{self.AUTH_URL}/oauth/authorize?"
f"client_id={self.platform_id}&"
f"redirect_uri={self.callback_url}&"
f"response_type=code"
)
def exchange_code(self, code: str) -> dict:
"""用授权码换取访问令牌"""
response = requests.post(
f"{self.BASE_URL}/api/oauth/token",
json={
"grant_type": "authorization_code",
"code": code,
"client_id": self.platform_id,
"client_secret": self.platform_secret,
"redirect_uri": self.callback_url
}
)
response.raise_for_status()
return response.json()
def get_user_info(self, access_token: str) -> dict:
"""获取用户信息"""
response = requests.get(
f"{self.BASE_URL}/api/oauth/userinfo",
headers={"Authorization": f"Bearer {access_token}"}
)
response.raise_for_status()
return response.json()
```
## 常见问题
### Q: 如何获取 platform_id 和 platform_token？
A: 在 SECTL Auth 平台管理页面申请创建平台，审核通过后会获得：
- platform_id (Client ID)
- platform_token (Client Secret)
### Q: 授权码有效期多久？
A: 授权码有效期为 10 分钟，且只能使用一次。
### Q: Access Token 过期后怎么办？
A: 使用 refresh_token 换取新的 access_token：
```http
POST /api/oauth/token
{
"grant_type": "refresh_token",
"refresh_token": "your-refresh-token",
"client_id": "your-platform-id",
"client_secret": "your-platform-secret"
}
```
### Q: 如何配置 Token 过期时间？
A: 在平台设置页面 ([PlatformSettingsView.vue](../../src/views/dashboard/other/PlatformSettingsView.vue)) 可以配置：
- access_token 过期时间（默认 3600 秒）
- 设置为 -1 表示永不过期
### Q: 远程退登不生效怎么办？
A: 检查以下几点：
1. 是否正确订阅了 `logout_events` 集合
2. 检查 user_id 是否匹配
3. 确认 Appwrite Realtime 连接正常
4. 查看浏览器控制台是否有错误
### Q: 平台状态显示"审核中"怎么办？
A: 新创建的平台需要管理员审核。审核通过后状态会变为 `active`。
## 相关页面
- [PlatformManagementView.vue](../../src/views/dashboard/manage/PlatformManagementView.vue) - 平台管理
- [PlatformDetailView.vue](../../src/views/dashboard/detail/PlatformDetailView.vue) - 平台详情
- [PlatformApplyView.vue](../../src/views/dashboard/form/PlatformApplyView.vue) - 申请平台
- [PlatformApplicationsView.vue](../../src/views/dashboard/manage/PlatformApplicationsView.vue) - 审核申请
- [PlatformSettingsView.vue](../../src/views/dashboard/other/PlatformSettingsView.vue) - 平台设置
- [LoginPlatformsView.vue](../../src/views/dashboard/list/LoginPlatformsView.vue) - 登录平台列表
## 参考文档
- [OAuth 2.0 流程](./OAUTH_FLOW.MD)
- [API 参考](./API_REFERENCE.md)
- [故障排查](../oauth-flow/TROUBLESHOOTING.md)
AUTH/OAUTH_FLOW.MD
+311
View File
@@ -0,0 +1,311 @@
# OAuth 2.0 授权流程文档
本文档详细说明 SECTL Auth 的 OAuth 2.0 授权流程，帮助第三方应用开发者接入统一认证服务。
## 概述
SECTL Auth 实现了标准的 OAuth 2.0 授权码流程（Authorization Code Flow），允许第三方应用使用 SECTL Auth 账户进行用户认证。
### 流程特点
- **安全性高** - 使用授权码模式，避免 Token 暴露在浏览器端
- **标准化** - 遵循 OAuth 2.0 RFC 6749 规范
- **远程退登** - 支持通过 Realtime 实现跨平台同步退出
- **可配置** - 支持自定义 Token 过期时间
## 授权流程
### 流程图
```
┌─────────┐ ┌─────────────┐
│ 用户 │ │ 第三方应用 │
└────┬────┘ └──────┬──────┘
│ │
│ 1. 访问应用 │
│───────────────────────────────────────────────>│
│ │
│ 2. 重定向到授权页面 │
│<───────────────────────────────────────────────│
│ │
│ 3. 登录并授权 (LoginView.vue / OAuthAuthorizeView.vue)
│───────────────────────────────────────────────>│
│ │
│ 4. 返回授权码 │
│<───────────────────────────────────────────────│
│ │
│ 5. 用授权码换取 Token │
│ │──────┐
│ │ │
│ 6. 返回 Access Token │<─────┘
│ │
│ 7. 使用 Token 访问用户资源 │
│<───────────────────────────────────────────────│
```
## 详细步骤
### 1. 引导用户到授权页面
当用户需要登录时，第三方应用应将用户重定向到 SECTL Auth 的授权页面。
**请求地址：**
```
GET https://sectl.top/oauth/authorize
```
**请求参数：**
| 参数名 | 必填 | 类型 | 说明 |
| ------------- | ---- | ------ | --------------------------------- |
| client_id | ✅ | string | 平台 ID，如 `pf_AHmIhAiptyLFxk8x` |
| redirect_uri | ✅ | string | 回调地址，必须与平台设置匹配 |
| response_type | ✅ | string | 固定值 `code` |
**示例 URL：**
```
https://sectl.top/oauth/authorize?client_id=pf_AHmIhAiptyLFxk8x&redirect_uri=http://localhost:5000/callback&response_type=code
```
**相关代码：** [OAuthAuthorizeView.vue](../../src/views/OAuthAuthorizeView.vue)
### 2. 用户登录与授权
用户将被引导至 SECTL Auth 登录页面（如果未登录）：
1. **登录页面** ([LoginView.vue](../../src/views/LoginView.vue))
- 用户输入邮箱密码或使用 GitHub 登录
- 支持记住我功能
- 检测 OAuth 参数，登录后自动跳转授权页
2. **授权确认页** ([OAuthAuthorizeView.vue](../../src/views/OAuthAuthorizeView.vue))
- 显示应用名称和图标
- 列出请求的权限范围
- 用户可选择"授权"或"拒绝"
**权限范围：**
- 访问用户基本信息（用户名、邮箱、头像）
- 验证用户身份
### 3. 获取授权码
用户授权后，页面将重定向到指定的回调地址：
```
{redirect_uri}?code={authorization_code}
```
**示例：**
```
http://localhost:5000/callback?code=NjliNDIyOTYwMDE4znLUNeWM6J8ye0MC
```
**授权码特性：**
- 有效期：10 分钟
- 一次性使用
- 与 `redirect_uri` 绑定
### 4. 换取访问令牌
第三方应用后端使用授权码向 SECTL Auth 换取访问令牌。
**请求地址：**
```
POST https://sectl.top/api/oauth/token
```
**请求头：**
```
Content-Type: application/json
```
**请求体：**
```json
{
"grant_type": "authorization_code",
"code": "NjliNDIyOTYwMDE4znLUNeWM6J8ye0MC",
"client_id": "pf_AHmIhAiptyLFxk8x",
"client_secret": "sk_UyMHuFf6oKXh8ZcHSb7lfOSgzumoOeg1",
"redirect_uri": "http://localhost:5000/callback"
}
```
**参数说明：**
| 参数名 | 必填 | 说明 |
| ------------- | ---- | --------------------------- |
| grant_type | ✅ | 固定值 `authorization_code` |
| code | ✅ | 上一步获取的授权码 |
| client_id | ✅ | 平台 ID |
| client_secret | ✅ | 平台密钥 |
| redirect_uri | ✅ | 必须与授权时一致 |
**成功响应：**
```json
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"refresh_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"token_type": "Bearer",
"expires_in": 3600
}
```
**Token 信息：**
| 字段 | 说明 |
| ------------- | ----------------------------------- |
| access_token | 访问令牌，用于调用 API |
| refresh_token | 刷新令牌，用于获取新的 access_token |
| token_type | 令牌类型，固定为 Bearer |
| expires_in | 过期时间（秒） |
### 5. 使用访问令牌
获取 access_token 后，可用于调用 SECTL Auth API 获取用户信息。
**获取用户信息：**
```http
GET https://sectl.top/api/oauth/userinfo
Authorization: Bearer {access_token}
```
**响应示例：**
```json
{
"user_id": "69bd422960018cf4d0e5",
"email": "user@example.com",
"name": "张三",
"github_username": "zhangsan"
}
```
## Token 管理
### 过期时间配置
平台可配置 Token 过期时间：
| 令牌类型 | 默认有效期 | 说明 |
| ------------- | --------------- | ---------------------- |
| access_token | 3600 秒 (1小时) | 短期有效，用于访问资源 |
| refresh_token | 长期有效 | 用于刷新 access_token |
| 授权码 | 600 秒 (10分钟) | 一次性使用 |
**修改过期时间：**
```http
POST https://sectl.top/api/oauth/config
Content-Type: application/json
{
"expires_in": 86400,
"admin_secret": "your-admin-secret"
}
```
### 刷新 Token
当 access_token 过期时，使用 refresh_token 获取新的令牌：
```http
POST https://sectl.top/api/oauth/token
Content-Type: application/json
{
"grant_type": "refresh_token",
"refresh_token": "your-refresh-token",
"client_id": "your-platform-id",
"client_secret": "your-platform-secret"
}
```
## 远程退登
SECTL Auth 支持远程退登功能，当用户在 SECTL Auth 中心退出登录时，已授权的第三方应用会收到通知。
### 实现原理
1. 用户在 SECTL Auth 点击退出登录
2. 系统创建 `logout_events` 文档
3. 第三方应用通过 Appwrite Realtime 订阅该集合
4. 收到退登事件后，应用执行本地退出操作
### 集成方式
详见 [平台接入指南](../platform-integration/README.md)。
## 错误处理
### 授权错误
当授权失败时，将重定向到回调地址并附带错误信息：
```
{redirect_uri}?error=access_denied&error_description=user+denied+authorization
```
**常见错误码：**
| 错误码 | 说明 |
| ------------------------- | ------------------ |
| invalid_request | 请求参数缺失或无效 |
| unauthorized_client | 客户端未授权 |
| access_denied | 用户拒绝授权 |
| unsupported_response_type | 不支持的响应类型 |
| invalid_scope | 无效的权限范围 |
| server_error | 服务器内部错误 |
### Token 错误
换取 Token 时的错误响应：
```json
{
"error": "invalid_grant",
"error_description": "Authorization code has expired"
}
```
**常见错误码：**
| 错误码 | 说明 |
| ---------------------- | ------------------------ |
| invalid_request | 请求格式错误 |
| invalid_client | 客户端认证失败 |
| invalid_grant | 授权码无效或过期 |
| unauthorized_client | 客户端无权使用此授权类型 |
| unsupported_grant_type | 不支持的授权类型 |
| invalid_scope | 无效的权限范围 |
## 安全建议
1. **使用 HTTPS** - 所有 OAuth 通信必须使用 HTTPS
2. **保护 client_secret** - 不要在客户端代码中暴露 client_secret
3. **验证 redirect_uri** - 确保回调地址与注册时一致
4. **使用状态参数** - 建议添加 `state` 参数防止 CSRF 攻击
5. **及时清理** - 使用后的授权码应立即作废
6. **安全存储** - Token 应安全存储，避免泄露
## 相关页面
- [LoginView.vue](../../src/views/LoginView.vue) - 登录页面
- [OAuthAuthorizeView.vue](../../src/views/OAuthAuthorizeView.vue) - OAuth 授权页面
- [AuthCallbackView.vue](../../src/views/AuthCallbackView.vue) - 认证回调处理
- [LoginPlatformsView.vue](../../src/views/dashboard/list/LoginPlatformsView.vue) - 登录平台列表
## 参考文档
- [平台接入指南](../platform-integration/README.md)
- [API 参考](../platform-integration/API_REFERENCE.md)
- [故障排查](./TROUBLESHOOTING.md)
AUTH/TROUBLESHOOTING.md
+476
View File
@@ -0,0 +1,476 @@
# OAuth 流程故障排查指南
本文档汇总了 SECTL Auth OAuth 流程中的常见问题及解决方案。
## 目录
- [授权阶段问题](#授权阶段问题)
- [Token 换取问题](#token-换取问题)
- [用户信息获取问题](#用户信息获取问题)
- [远程退登问题](#远程退登问题)
- [平台管理问题](#平台管理问题)
- [网络与 CORS 问题](#网络与-cors-问题)
---
## 授权阶段问题
### 1. 授权页面无法打开
**现象：** 访问授权 URL 返回 404 或空白页面
**排查步骤：**
1. 检查 URL 格式是否正确
```
https://auth.sectl.top/oauth/authorize?client_id=xxx&redirect_uri=xxx&response_type=code
```
2. 确认必要参数是否齐全
- `client_id` - 平台 ID
- `redirect_uri` - 回调地址
- `response_type` - 固定值 `code`
3. 检查平台是否存在且状态为 `active`
- 登录 SECTL Auth 管理后台
- 查看 [PlatformManagementView.vue](../../src/views/dashboard/manage/PlatformManagementView.vue)
- 确认平台状态不是 `pending` 或 `disabled`
**相关页面：**
- [OAuthAuthorizeView.vue](../../src/views/OAuthAuthorizeView.vue)
- [PlatformManagementView.vue](../../src/views/dashboard/manage/PlatformManagementView.vue)
---
### 2. 授权后没有记录到登录平台
**现象：** 用户授权后，在"登录平台"页面 ([LoginPlatformsView.vue](../../src/views/dashboard/list/LoginPlatformsView.vue)) 看不到记录
**排查步骤：**
1. 检查浏览器控制台是否有错误
2. 检查 `user_data` 集合是否有该用户的记录
3. 检查 `user_data.login_platforms` 字段是否正确更新
4. 检查 `oauth_tokens` 集合是否有对应的令牌记录
**可能原因：**
- 用户未登录 SECTL Auth
- `user_data` 集合权限问题
- 网络请求失败
- 平台状态为 `disabled`
**相关页面：**
- [LoginPlatformsView.vue](../../src/views/dashboard/list/LoginPlatformsView.vue)
- [SecurityView.vue](../../src/views/dashboard/other/SecurityView.vue)
---
### 3. 用户已登录但授权页面仍要求登录
**现象：** 用户已登录 SECTL Auth，但授权页面仍跳转到登录页
**排查步骤：**
1. 检查登录状态是否正确保持
2. 检查浏览器 Cookie 是否被阻止
3. 检查是否跨域问题
**解决方案：**
- 确保浏览器允许第三方 Cookie
- 检查 `rememberMe` 选项是否勾选
- 查看 [LoginView.vue](../../src/views/LoginView.vue) 中的登录逻辑
---
## Token 换取问题
### 1. 换取 token 时提示 "Invalid authorization code"
**现象：** 用 code 换取 token 返回 400 错误
```json
{
"error": "invalid_grant",
"error_description": "Invalid authorization code"
}
```
**排查步骤：**
1. 检查 code 是否已过期（10分钟有效期）
2. 检查 code 是否已被使用过
3. 检查 `redirect_uri` 是否与授权时一致
4. 检查 `client_id` 和 `client_secret` 是否正确
**可能原因：**
- Code 已过期
- Code 已被使用（一次性）
- 回调地址不匹配
- 平台密钥错误
**相关代码：** [AuthCallbackView.vue](../../src/views/AuthCallbackView.vue)
---
### 2. 换取 token 时提示 "Invalid client"
**现象：** 返回 401 错误
```json
{
"error": "invalid_client",
"error_description": "Client authentication failed"
}
```
**排查步骤：**
1. 确认 `client_id` 正确
2. 确认 `client_secret` 正确且未泄露
3. 检查平台状态是否为 `active`
**解决方案：**
- 在 [PlatformManagementView.vue](../../src/views/dashboard/manage/PlatformManagementView.vue) 查看平台信息
- 如密钥泄露，在 [PlatformSettingsView.vue](../../src/views/dashboard/other/PlatformSettingsView.vue) 重置密钥
---
### 3. Access Token 过期后无法刷新
**现象：** 使用 refresh_token 换取新 token 失败
**排查步骤：**
1. 检查 refresh_token 是否有效
2. 检查 refresh_token 是否被撤销
3. 检查平台是否被禁用
**请求示例：**
```http
POST /api/oauth/token
{
"grant_type": "refresh_token",
"refresh_token": "your-refresh-token",
"client_id": "your-platform-id",
"client_secret": "your-platform-secret"
}
```
---
## 用户信息获取问题
### 1. 获取用户信息返回 401
**现象：** 调用 `/api/oauth/userinfo` 返回未授权错误
**排查步骤：**
1. 检查 access_token 是否过期
2. 检查 Authorization 头格式是否正确
```
Authorization: Bearer {access_token}
```
3. 检查 token 是否被撤销
**解决方案：**
- 使用 refresh_token 获取新的 access_token
- 重新走授权流程
**相关页面：** [PlatformUsersView.vue](../../src/views/dashboard/manage/PlatformUsersView.vue)
---
### 2. 用户信息字段缺失
**现象：** 返回的用户信息缺少某些字段
**排查步骤：**
1. 检查用户是否设置了该字段
2. 检查数据库中 `user_data` 集合是否有该字段
**响应示例：**
```json
{
"user_id": "69bd422960018cf4d0e5",
"email": "user@example.com",
"name": "张三",
"github_username": "zhangsan",
"permission": 1
}
```
---
## 远程退登问题
### 1. 远程退登不生效
**现象：** 用户在 SECTL Auth 退出后，第三方平台没有自动退出
**排查步骤：**
1. 检查是否正确订阅了 `logout_events` 集合
2. 检查 user_id 是否匹配
3. 确认 Appwrite Realtime 连接正常
4. 查看浏览器控制台是否有错误
**订阅代码示例：**
```javascript
client.subscribe(
"databases.69bd89d8000304c37368.collections.logout_events.documents",
(response) => {
const event = response.payload
if (event.user_id === currentUserId) {
localLogout()
}
}
)
```
**相关页面：**
- [SecurityView.vue](../../src/views/dashboard/other/SecurityView.vue)
- [PlatformManagementView.vue](../../src/views/dashboard/manage/PlatformManagementView.vue)
---
### 2. Realtime 连接断开
**现象：** 退登事件偶尔收不到
**排查步骤：**
1. 检查网络连接稳定性
2. 检查是否有心跳机制保持连接
3. 检查浏览器是否进入休眠状态
**解决方案：**
- 实现重连机制
- 定期检查连接状态
- 使用 Service Worker 保持后台连接
---
## 平台管理问题
### 1. 平台管理的"登录用户"为空
**现象：** 在平台管理页面查看登录用户，显示为空
**排查步骤：**
1. 检查 `oauth_tokens` 集合是否有记录
2. 检查记录是否有 `user_id` 字段
3. 检查 `oauth_tokens` 集合权限
**解决方案：**
如果 `oauth_tokens` 没有 `user_id` 字段，需要在 Appwrite Console 中添加：
1. 进入 Database → 选择数据库
2. 找到 `oauth_tokens` 集合
3. 添加字段：`user_id`（String 类型，非必填）
**相关页面：**
- [PlatformManagementView.vue](../../src/views/dashboard/manage/PlatformManagementView.vue)
- [PlatformUsersView.vue](../../src/views/dashboard/manage/PlatformUsersView.vue)
---
### 2. 平台状态显示"审核中"
**现象：** 新创建的平台无法使用，状态为 `pending`
**排查步骤：**
1. 检查是否已提交平台申请
2. 联系管理员审核
3. 在 [MyPlatformApplicationsView.vue](../../src/views/dashboard/manage/MyPlatformApplicationsView.vue) 查看申请状态
**解决方案：**
- 等待管理员审核
- 管理员在 [PlatformApplicationsView.vue](../../src/views/dashboard/manage/PlatformApplicationsView.vue) 中批准申请
---
### 3. 无法修改平台回调地址
**现象：** 在平台设置中修改回调地址失败
**排查步骤：**
1. 检查是否有权限修改（所有者或管理员）
2. 检查回调地址格式是否正确
3. 检查数据库权限配置
**相关页面：** [PlatformSettingsView.vue](../../src/views/dashboard/other/PlatformSettingsView.vue)
---
## 网络与 CORS 问题
### 1. CORS 错误
**现象：** 浏览器控制台显示 CORS 错误
**错误信息：**
```
Access to fetch at 'https://auth.sectl.top/...' from origin 'https://auth.sectl.top' has been blocked by CORS policy
```
**解决方案：**
已在 OAuth API 中添加 CORS 头：
```javascript
res.setHeader("Access-Control-Allow-Origin", "*")
res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization")
```
**排查步骤：**
1. 确认请求头是否正确
2. 确认是否为预检请求（OPTIONS）问题
3. 检查服务器 CORS 配置
---
### 2. 授权码中的用户ID解码失败
**现象：** 换取 token 后 `user_id` 为 "anonymous"
**排查步骤：**
1. 检查授权码格式（应为 32 位：前16位 base64 用户ID + 后16位随机）
2. 检查 `oauth_codes` 集合是否有 `user_id` 字段
**代码逻辑：**
```javascript
// 生成授权码时编码用户ID
const userIdHash = Buffer.from(userId)
.toString("base64")
.replace(/[^a-zA-Z0-9]/g, "")
.substring(0, 16)
const code = userIdHash + randomPart
// 换取 token 时解码
try {
const userIdHash = code.substring(0, 16)
const base64Str = userIdHash.replace(/_/g, "/").replace(/-/g, "+") + "=="
const decoded = Buffer.from(base64Str, "base64").toString("utf8")
tokenUserId = decoded
} catch (e) {
tokenUserId = "anonymous"
}
```
---
### 3. 网络超时
**现象：** 请求 OAuth API 超时
**排查步骤：**
1. 检查网络连接
2. 检查服务器状态
3. 增加请求超时时间
**解决方案：**
```javascript
// 增加超时时间
const response = await fetch(url, {
...options,
signal: AbortSignal.timeout(30000), // 30秒超时
})
```
---
## 调试技巧
### 1. 浏览器开发者工具
使用浏览器开发者工具排查问题：
1. **Network 面板** - 查看请求和响应
2. **Console 面板** - 查看错误日志
3. **Application 面板** - 查看 Cookie 和 LocalStorage
### 2. Appwrite Console
在 Appwrite Console 中检查：
1. **Database** - 检查集合数据和权限
2. **Auth** - 检查用户和会话
3. **Functions** - 查看函数日志
4. **Realtime** - 检查实时连接
### 3. 日志记录
在关键位置添加日志：
```javascript
// 授权流程日志
console.log("OAuth params:", { client_id, redirect_uri, response_type })
console.log("Authorization code:", code)
console.log("Token response:", tokenData)
// 退登事件日志
console.log("Logout event received:", event)
console.log("Current user ID:", currentUserId)
```
---
## 常见问题速查表
| 问题 | 可能原因 | 解决方案 |
| :------------- | :------------------- | :---------------------- |
| 授权页面 404 | 平台不存在或状态异常 | 检查平台状态和 ID |
| Invalid code | Code 过期或已使用 | 重新授权获取新 code |
| Invalid client | 密钥错误 | 检查 client_secret |
| Token 过期 | 超过 expires_in | 使用 refresh_token 刷新 |
| 用户信息 401 | Token 无效 | 检查 Token 格式和有效期 |
| 退登不生效 | Realtime 未连接 | 检查订阅代码 |
| CORS 错误 | 跨域配置问题 | 检查服务器 CORS 头 |
---
## 获取帮助
如果以上方案无法解决问题：
1. 查看 [API 参考](../platform-integration/API_REFERENCE.md)
2. 查看 [平台接入指南](../platform-integration/README.md)
3. 提交 Issue 到项目仓库
4. 联系管理员
---
## 相关页面
- [OAuthAuthorizeView.vue](../../src/views/OAuthAuthorizeView.vue) - OAuth 授权页面
- [AuthCallbackView.vue](../../src/views/AuthCallbackView.vue) - 认证回调
- [LoginView.vue](../../src/views/LoginView.vue) - 登录页面
- [PlatformManagementView.vue](../../src/views/dashboard/manage/PlatformManagementView.vue) - 平台管理
- [PlatformSettingsView.vue](../../src/views/dashboard/other/PlatformSettingsView.vue) - 平台设置
- [SecurityView.vue](../../src/views/dashboard/other/SecurityView.vue) - 安全设置
- [LoginPlatformsView.vue](../../src/views/dashboard/list/LoginPlatformsView.vue) - 登录平台列表
src/components/OAuthCallback.tsx
+49
View File
@@ -0,0 +1,49 @@
import { useEffect } from "react"
import { useSearchParams, useNavigate } from "react-router-dom"
export function OAuthCallback() {
const [searchParams] = useSearchParams()
const navigate = useNavigate()
useEffect(() => {
const code = searchParams.get("code")
const error = searchParams.get("error")
const errorDescription = searchParams.get("error_description")
if (error) {
window.postMessage(
{
error: errorDescription || error,
},
window.location.origin
)
navigate("/")
return
}
if (code) {
window.postMessage(
{
code,
},
window.location.origin
)
navigate("/")
}
}, [searchParams, navigate])
return (
<div
style={{
display: "flex",
justifyContent: "center",
alignItems: "center",
height: "100vh",
background: "var(--ss-bg-color)",
color: "var(--ss-text-main)",
}}
>
<div>正在处理登录...</div>
</div>
)
}
src/components/OAuthLogin.tsx
+183
View File
@@ -0,0 +1,183 @@
import { Button, message, Modal, Space, Spin } from "antd"
import { useEffect, useRef, useState } from "react"
import { useTranslation } from "react-i18next"
import { open } from "@tauri-apps/plugin-shell"
import { listen, UnlistenFn } from "@tauri-apps/api/event"
interface OAuthLoginProps {
visible: boolean
onClose: () => void
onSuccess: (userInfo: {
user_id: string
email: string
name: string
github_username?: string
permission: number
}) => void
}
interface OAuthConfig {
platform_id: string
platform_secret: string
callback_url: string
}
export function OAuthLogin({ visible, onClose, onSuccess }: OAuthLoginProps) {
const { t } = useTranslation()
const [loading, setLoading] = useState(false)
const deepLinkUnlistenRef = useRef<UnlistenFn | null>(null)
const getOAuthConfig = (): OAuthConfig | null => {
const api = (window as any).api
if (!api) return null
const platformId = import.meta.env.VITE_OAUTH_PLATFORM_ID
const platformSecret = import.meta.env.VITE_OAUTH_PLATFORM_SECRET
const callbackUrl = import.meta.env.VITE_OAUTH_CALLBACK_URL || "secscore://oauth/callback"
if (!platformId || !platformSecret) {
return null
}
return {
platform_id: platformId,
platform_secret: platformSecret,
callback_url: callbackUrl,
}
}
const handleDeepLink = async (url: string) => {
const config = getOAuthConfig()
if (!config) return
try {
const urlObj = new URL(url)
const code = urlObj.searchParams.get("code")
const error = urlObj.searchParams.get("error")
if (error) {
message.error(decodeURIComponent(error))
setLoading(false)
return
}
if (code) {
const api = (window as any).api
const tokenRes = await api.oauthExchangeCode(
code,
config.platform_id,
config.platform_secret,
config.callback_url
)
if (!tokenRes.success) {
message.error(tokenRes.message || "获取访问令牌失败")
setLoading(false)
return
}
const userRes = await api.oauthGetUserInfo(tokenRes.data.access_token)
if (!userRes.success) {
message.error(userRes.message || "获取用户信息失败")
setLoading(false)
return
}
onSuccess(userRes.data)
onClose()
}
} catch (error: any) {
message.error(error.message || "登录失败")
} finally {
setLoading(false)
}
}
useEffect(() => {
const setupDeepLink = async () => {
try {
const unlisten = await listen<string>("deep-link://new-url", (event) => {
if (event.payload) {
handleDeepLink(event.payload)
}
})
deepLinkUnlistenRef.current = unlisten
} catch (error) {
console.error("Failed to setup deep link listener:", error)
}
}
setupDeepLink()
return () => {
if (deepLinkUnlistenRef.current) {
deepLinkUnlistenRef.current()
deepLinkUnlistenRef.current = null
}
}
}, [])
const handleOAuthLogin = async () => {
const config = getOAuthConfig()
if (!config) {
message.error("OAuth 配置未设置")
return
}
setLoading(true)
try {
const api = (window as any).api
const urlRes = await api.oauthGetAuthorizationUrl(config.platform_id, config.callback_url)
if (!urlRes.success) {
message.error(urlRes.message || "获取授权链接失败")
setLoading(false)
return
}
await open(urlRes.data)
} catch (error: any) {
message.error(error.message || "登录失败")
setLoading(false)
}
}
return (
<Modal
title={t("auth.oauthLogin", "SECTL Auth 登录")}
open={visible}
onCancel={onClose}
footer={null}
width={400}
centered
>
<div style={{ textAlign: "center", padding: "20px 0" }}>
{loading ? (
<Space direction="vertical" size="middle">
<Spin size="large" />
<div>{t("auth.oauthLoggingIn", "正在登录...")}</div>
<div style={{ fontSize: "12px", color: "var(--ss-text-secondary)" }}>
请在浏览器中完成授权
</div>
</Space>
) : (
<Space direction="vertical" size="large" style={{ width: "100%" }}>
<div style={{ color: "var(--ss-text-secondary)" }}>
{t("auth.oauthHint", "使用 SECTL Auth 账号登录,享受统一认证和远程退登功能")}
</div>
<Button
type="primary"
size="large"
onClick={handleOAuthLogin}
style={{ width: "100%" }}
>
{t("auth.oauthButton", "使用 SECTL Auth 登录")}
</Button>
</Space>
)}
</div>
</Modal>
)
}