Northern_Lights/app

Fork 0

mirror of https://github.com/StarCitizenToolBox/app.git synced 2026-01-13 19:50:28 +00:00

xkeyC 724f7d8242 feat: oidc support

2025-12-26 16:39:12 +08:00

3.7 KiB

Raw Blame History

SCToolBox OAuth 认证系统

快速开始

授权流程

┌─────────┐      ┌──────────┐      ┌────────────┐      ┌──────────┐
│ Web App │──1──▶│ Browser  │──2──▶│ SCToolBox  │──3──▶│  Server  │
└─────────┘      └──────────┘      └────────────┘      └──────────┘
     ▲                                     │                   │
     │                                     ├──4──▶ 验证域名    │
     │                                     │       安全性      │
     │                                     │                   │
     │                                     ├──5──▶ 生成 JWT   │
     │                                     │       令牌        │
     │                                     │                   │
     └─────────────────6─────────────────┘                   │
                  返回令牌                                     │

URL Scheme 格式

sctoolbox://auth/{domain}?callbackUrl={回调地址}

示例

sctoolbox://auth/example.com?callbackUrl=https%3A%2F%2Fexample.com%2Fauth%2Fcallback

回调格式

{callbackUrl}#access_token={jwt_token}&token_type=Bearer

功能特性

✅ 基于 JWT 的安全认证
✅ 域名白名单验证
✅ 跨平台支持（Windows、macOS、Linux）
✅ 两种授权方式（直接跳转 / 复制链接）
✅ 符合 OAuth 2.0 Implicit Flow 标准

实现文件

核心文件

lib/ui/auth/auth_page.dart - 授权页面 UI
lib/ui/auth/auth_ui_model.dart - 授权页面状态管理
lib/common/utils/url_scheme_handler.dart - URL Scheme 处理器

平台配置

macos/Runner/Info.plist - macOS URL Scheme 配置
windows/runner/main.cpp - Windows Deep Link 处理
linux/my_application.cc - Linux Deep Link 处理
linux/sctoolbox.desktop - Linux MIME 类型注册
pubspec.yaml - MSIX 协议激活配置

使用方法

初始化

URL Scheme handler 在 IndexUI 中自动初始化：

useEffect(() {
  UrlSchemeHandler().initialize(context);
  return () => UrlSchemeHandler().dispose();
}, const []);

Web 应用集成

// 发起授权
const authUrl = `sctoolbox://auth/example.com?callbackUrl=${encodeURIComponent(callbackUrl)}`;
window.location.href = authUrl;

// 处理回调
const params = new URLSearchParams(window.location.hash.substring(1));
const token = params.get('access_token');

平台要求

Windows: 需要使用 MSIX 打包版本
macOS: 需要配置 Info.plist
Linux: 需要注册 .desktop 文件

安全性

✅ JWT 签名验证
✅ 域名白名单检查
✅ 令牌过期时间控制
✅ 使用 Fragment (#) 传递令牌（更安全）

详细文档

查看完整文档了解更多信息，包括：

详细的授权流程
API 接口说明
Web 应用集成示例
安全最佳实践
常见问题解答

API 端点

认证服务提供以下 gRPC 接口：

GenerateToken - 生成 JWT 令牌
ValidateToken - 验证令牌有效性
GetPublicKey - 获取公钥用于验证
GetJWTDomainList - 获取可信域名列表

测试

# macOS/Linux
open "sctoolbox://auth/test.example.com?callbackUrl=https%3A%2F%2Ftest.example.com%2Fcallback"

# Windows
start "sctoolbox://auth/test.example.com?callbackUrl=https%3A%2F%2Ftest.example.com%2Fcallback"

3.7 KiB Raw Blame History Unescape Escape