nuxt-app/docs/superpowers/oauth2/PROVIDERS.md

OAuth2 Provider 配置文档

创建日期：2026-05-26

---

概述

OAuth2 模块采用配置驱动的架构设计，内置 Provider 通过配置文件注册，添加新 Provider 只需配置无需编写代码。

---

内置 Provider

GitHub

配置项：

环境变量	说明
GITHUB_CLIENT_ID	GitHub OAuth App 的 Client ID
GITHUB_CLIENT_SECRET	GitHub OAuth App 的 Client Secret

申请步骤：

1. 登录 GitHub Developer Settings
2. 点击 "New OAuth App"
3. 填写应用信息：
   • Application name: 应用名称
   • Homepage URL: http://localhost:3000（开发环境）
   • Authorization callback URL: http://localhost:3000/api/auth/oauth/github/callback
4. 创建后复制 Client ID 和 Client Secret

权限范围： read:user user:email

用户信息映射：

{
  "id": 123456,                    // -> providerUserId
  "login": "username",              // -> username
  "email": "user@example.com",     // -> email (需授权)
  "avatar_url": "https://..."      // -> avatar
}

---

Google (预留)

配置项：

环境变量	说明
GOOGLE_CLIENT_ID	Google OAuth 2.0 Client ID
GOOGLE_CLIENT_SECRET	Google OAuth 2.0 Client Secret

申请步骤：

1. 登录 Google Cloud Console
2. 创建项目（或选择已有项目）
3. 启用 Google+ API
4. 配置 OAuth consent screen
5. 创建 OAuth 2.0 Client ID凭据
6. 添加回调 URL：http://localhost:3000/api/auth/oauth/google/callback

权限范围： openid email profile

用户信息映射：

{
  "sub": "123456789",              // -> providerUserId
  "name": "User Name",             // -> username
  "email": "user@example.com",     // -> email
  "picture": "https://..."         // -> avatar
}

---

添加自定义 Provider

方式一：配置驱动（推荐）

对于标准 OAuth2 Provider，只需在 Provider 注册表中添加配置：

// packages/oauth/src/providers/index.ts
import { GitHubProvider } from './github';
import { createOAuthProviders } from './factory';

export const oauthProviders = createOAuthProviders({
  github: new GitHubProvider({
    clientId: process.env.GITHUB_CLIENT_ID!,
    clientSecret: process.env.GITHUB_CLIENT_SECRET!,
  }),
  // 添加新 Provider：
  // myprovider: new CustomProvider({
  //   clientId: process.env.MYPROVIDER_CLIENT_ID!,
  //   clientSecret: process.env.MYPROVIDER_CLIENT_SECRET!,
  //   // 自定义配置...
  // }),
});

方式二：实现 Provider 接口

对于非标准 OAuth2 Provider，需要实现 OAuthProvider 接口：

// packages/oauth/src/providers/custom.ts
import type { OAuthProvider, OAuthUserInfo } from './base';
import { z } from 'zod';

export class CustomProvider implements OAuthProvider {
  name = 'custom';
  icon = '🔐';
  clientId: string;
  clientSecret: string;
  authorizeUrl = 'https://custom.example.com/oauth/authorize';
  tokenUrl = 'https://custom.example.com/oauth/token';
  userInfoUrl = 'https://custom.example.com/oauth/userinfo';
  scopes = ['read:user'];

  constructor(config: { clientId: string; clientSecret: string }) {
    this.clientId = config.clientId;
    this.clientSecret = config.clientSecret;
  }

  mapUserInfo(raw: Record<string, unknown>): OAuthUserInfo {
    return {
      provider: this.name,
      providerUserId: String(raw.id),
      username: String(raw.username ?? ''),
      email: String(raw.email ?? ''),
      avatar: String(raw.avatar_url ?? ''),
    };
  }
}

---

Provider 接口规范

interface OAuthProvider {
  // 提供商名称（唯一标识）
  name: string;

  // 图标（emoji 或 Icon 组件名）
  icon: string;

  // OAuth 配置
  clientId: string;
  clientSecret: string;
  authorizeUrl: string;
  tokenUrl: string;
  userInfoUrl: string;
  scopes: string[];

  // 用户信息映射
  mapUserInfo(raw: Record<string, unknown>): OAuthUserInfo;
}

---

环境变量配置示例

# .env 或 .env.local

# GitHub OAuth
GITHUB_CLIENT_ID=Iv1.xxxxxxxxxxxxxxxx
GITHUB_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Google OAuth (预留)
GOOGLE_CLIENT_ID=xxxxx-xxxxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=xxxxx-xxxxx

---

Provider 开发检查清单

• 在 Provider 设置平台 注册应用
• 配置正确的回调 URL：https://your-domain.com/api/auth/oauth/{provider}/callback
• 获取 clientId 和 clientSecret
• 设置环境变量
• 实现 mapUserInfo 方法（字段映射）
• 测试完整的 OAuth 流程
• 验证用户信息正确获取（username、email、avatar）