[RFC] 121 - 桌面端 OAuth 认证流程重构

[arvinxx]

摘要

本RFC描述了 LobeChat 桌面端OAuth认证流程的重构，从基于自定义协议处理器的方式改为基于Web页面重定向和轮询机制的解决方案。这一变更解决了原有方案在不同操作系统环境下的兼容性问题，提供了更可靠的跨平台认证体验。

问题背景

• 🐛 fix: cant invoke the application after OIDC authorization in Windows 11 #7900
• 🐛 fix: fix oidc redirect urls #7558

现有实现的问题

1. 自定义协议处理器的局限性

原始实现方式：

• 使用 com.lobehub.${name}://auth/callback 格式的自定义协议
• 通过 app.setAsDefaultProtocolClient 注册协议处理器
• 监听 open-url 事件（macOS）和 second-instance 事件（Windows/Linux）

存在的问题：

• Windows兼容性：在Windows 11 环境下，OIDC授权后经常无法正确唤起应用
• 协议注册不可靠：自定义协议的注册和处理在不同系统版本间存在差异，浏览器不一定正常兼容（ [Feedback] LobeChat Desktop Public Beta | LobeChat 桌面端 Beta 版开始公测 #7594 (comment) ）
• 用户体验差：协议处理失败时缺乏明确的错误提示
• 部署适配性： Cloudflare 兼容性问题： [Feedback] LobeChat Desktop Public Beta | LobeChat 桌面端 Beta 版开始公测 #7594 (comment)

解决方案

核心设计理念

采用Web页面重定向 + 轮询机制的混合方案，结合Web技术的成熟性和桌面端的控制能力。

新架构设计

1. Handoff机制

概念：

• 引入"handoff"概念，作为认证凭证的临时存储和传递机制
• 每次认证请求生成唯一的handoff ID
• 通过该ID实现认证凭证的安全传递

实现：

// 生成唯一的handoff ID
this.handoffId = crypto.randomUUID();

// 构建重定向URL，使用Web页面而非自定义协议
const redirectUri = `${remoteUrl}/oidc/callback/desktop`;

2. 认证流程重构

新的认证流程：

1. 发起认证请求

   • 生成PKCE参数和状态参数
   • 生成唯一的handoff ID 作为 state
   • 构建授权URL，重定向至Web页面

2. Web页面处理

   • 用户在浏览器中完成OAuth认证
   • 认证成功后重定向到 /oidc/callback/desktop
   • 后端将认证凭证存储到 handoff 表中

3. 轮询获取凭证

   • 桌面端启动轮询机制
   • 定期调用 /oidc/handoff API检查凭证状态
   • 获取到凭证后完成令牌交换

3. 数据库设计

OAuth Handoff表：

CREATE TABLE oauth_handoffs (
  id TEXT PRIMARY KEY,           -- 客户端生成的唯一标识符
  client VARCHAR(50) NOT NULL,   -- 客户端类型 (desktop, mobile, etc.)
  payload JSONB NOT NULL,        -- 认证凭证数据
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

TTL控制：

• 凭证在创建后5分钟内有效
• 消费后立即删除记录
• 定期清理过期记录

技术实现细节

1. 前端实现

AuthCtr控制器重构：

async requestAuthorization(config: DataSyncConfig) {
  // 生成PKCE参数
  const codeVerifier = this.generateCodeVerifier();
  const codeChallenge = await this.generateCodeChallenge(codeVerifier);
  
  // 生成状态参数和handoff ID
  this.authRequestState = crypto.randomBytes(16).toString('hex');
  this.handoffId = crypto.randomUUID();
  
  // 构建授权URL - 重定向到Web页面
  const authUrl = new URL('/oidc/auth', remoteUrl);
  const redirectUri = `${remoteUrl}/oidc/callback/desktop`;
  
  // 启动轮询
  this.startPolling();
  
  // 在浏览器中打开授权URL
  await shell.openExternal(authUrl.toString());
}

轮询机制：

private startPolling() {
  const pollInterval = 3000; // 3秒间隔
  const maxPollTime = 5 * 60 * 1000; // 5分钟超时
  
  this.pollingInterval = setInterval(async () => {
    const result = await this.pollForCredentials();
    if (result) {
      this.stopPolling();
      await this.exchangeCodeForToken(result.code, this.codeVerifier);
    }
  }, pollInterval);
}

2. 后端实现

回调路由处理：

// /oidc/callback/desktop
export const GET = async (req: NextRequest) => {
  const code = searchParams.get('code');
  const state = searchParams.get('state'); // handoff ID
  
  // 存储凭证到handoff表
  await authHandoffModel.create({
    client: 'desktop',
    id: state,
    payload: { code, state }
  });
  
  // 重定向到成功页面
  return NextResponse.redirect('/oauth/callback/success');
};

轮询API：

// /oidc/handoff
export const GET = async (req: NextRequest) => {
  const id = searchParams.get('id');
  const client = searchParams.get('client');
  
  // 查询handoff记录
  const record = await authHandoffModel.findByIdAndClient(id, client);
  
  if (!record) {
    return NextResponse.json({ error: 'Not found' }, { status: 404 });
  }
  
  // 返回凭证并删除记录
  await authHandoffModel.deleteById(id);
  return NextResponse.json({ success: true, data: record });
};

3. 错误处理和恢复

窗口显示问题修复：

app.on('second-instance', async (event, commandLine) => {
  const { success } = await this.handleAuthCallback(url);
  if (success) {
    // 确保窗口显示在前台
    this.app.browserManager.getMainWindow().show();
  }
});

超时和重试机制：

• 轮询超时：5分钟
• 轮询间隔：3秒
• 自动重试：支持手动重试连接

结论

OAuth认证流程的重构成功解决了桌面端在不同操作系统环境下的兼容性问题，提供了更可靠、更安全的认证体验。通过引入Web页面重定向和轮询机制，我们实现了：

1. 跨平台兼容性：消除了自定义协议的依赖
2. 可靠性提升：标准HTTP技术确保稳定性
3. 安全性增强：改进的状态验证和凭证传递
4. 用户体验优化：清晰的错误提示和恢复机制

这一重构为LobeChat桌面端的OAuth认证建立了坚实的技术基础，为未来的扩展和优化提供了良好的架构支撑。

进展

• ✨ feat: refactor desktop oauth and use JWTs token to support remote chat #8446

[Wxh16144]

自定义协议打开应用这个功能挺好用的，能否判断授权页是 chrome 和 macos 的时候开启自定义协议唤醒 app 功能呀。