Back to Details

oauth-social-login

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OAuth Social Login

OAuth 社交登录

Add "Sign in with Google/GitHub" to your app.
为你的应用添加「使用Google/GitHub登录」功能。

When to Use This Skill

何时使用该方案

  • Adding social login options
  • Reducing signup friction
  • Linking multiple auth providers to one account
  • Enterprise SSO requirements
  • 添加社交登录选项
  • 降低注册门槛
  • 将多个认证服务商关联到同一账号
  • 企业级单点登录需求

Architecture

架构流程

┌─────────────────────────────────────────────────────┐
│                    User clicks                       │
│               "Sign in with Google"                  │
└─────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────┐
│              Redirect to Provider                    │
│                                                     │
│  /auth/google → Google OAuth consent screen         │
│  Include: client_id, redirect_uri, scope, state     │
└─────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────┐
│              Provider Callback                       │
│                                                     │
│  /auth/google/callback?code=xxx&state=yyy          │
│  1. Verify state (CSRF protection)                  │
│  2. Exchange code for tokens                        │
│  3. Fetch user profile                              │
│  4. Create/link user account                        │
│  5. Issue session/JWT                               │
└─────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────┐
│                    用户点击                       │
│               「使用Google登录」                  │
└─────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────┐
│              重定向至认证服务商                    │
│                                                     │
│  /auth/google → Google OAuth 授权同意页面         │
│  包含参数: client_id, redirect_uri, scope, state     │
└─────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────┐
│              服务商回调处理                       │
│                                                     │
│  /auth/google/callback?code=xxx&state=yyy          │
│  1. 验证state参数（CSRF防护）                  │
│  2. 用授权码交换令牌                        │
│  3. 获取用户个人资料                              │
│  4. 创建/关联用户账号                        │
│  5. 签发会话/JWT                               │
└─────────────────────────────────────────────────────┘

TypeScript Implementation

TypeScript 实现

OAuth Configuration

OAuth 配置

typescript
// oauth-config.ts
interface OAuthProvider {
  name: string;
  clientId: string;
  clientSecret: string;
  authorizationUrl: string;
  tokenUrl: string;
  userInfoUrl: string;
  scopes: string[];
}

const providers: Record<string, OAuthProvider> = {
  google: {
    name: 'Google',
    clientId: process.env.GOOGLE_CLIENT_ID!,
    clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
    tokenUrl: 'https://oauth2.googleapis.com/token',
    userInfoUrl: 'https://www.googleapis.com/oauth2/v2/userinfo',
    scopes: ['openid', 'email', 'profile'],
  },
  github: {
    name: 'GitHub',
    clientId: process.env.GITHUB_CLIENT_ID!,
    clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    authorizationUrl: 'https://github.com/login/oauth/authorize',
    tokenUrl: 'https://github.com/login/oauth/access_token',
    userInfoUrl: 'https://api.github.com/user',
    scopes: ['read:user', 'user:email'],
  },
};

export { providers, OAuthProvider };
typescript
// oauth-config.ts
interface OAuthProvider {
  name: string;
  clientId: string;
  clientSecret: string;
  authorizationUrl: string;
  tokenUrl: string;
  userInfoUrl: string;
  scopes: string[];
}

const providers: Record<string, OAuthProvider> = {
  google: {
    name: 'Google',
    clientId: process.env.GOOGLE_CLIENT_ID!,
    clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
    tokenUrl: 'https://oauth2.googleapis.com/token',
    userInfoUrl: 'https://www.googleapis.com/oauth2/v2/userinfo',
    scopes: ['openid', 'email', 'profile'],
  },
  github: {
    name: 'GitHub',
    clientId: process.env.GITHUB_CLIENT_ID!,
    clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    authorizationUrl: 'https://github.com/login/oauth/authorize',
    tokenUrl: 'https://github.com/login/oauth/access_token',
    userInfoUrl: 'https://api.github.com/user',
    scopes: ['read:user', 'user:email'],
  },
};

export { providers, OAuthProvider };

OAuth Service

OAuth 服务

typescript
// oauth-service.ts
import crypto from 'crypto';
import { providers, OAuthProvider } from './oauth-config';

interface OAuthTokens {
  accessToken: string;
  refreshToken?: string;
  expiresIn?: number;
  tokenType: string;
}

interface OAuthUserInfo {
  id: string;
  email: string;
  name?: string;
  picture?: string;
  provider: string;
}

class OAuthService {
  private stateStore = new Map<string, { provider: string; redirectTo?: string }>();

  generateAuthUrl(providerName: string, redirectTo?: string): string {
    const provider = providers[providerName];
    if (!provider) throw new Error(`Unknown provider: ${providerName}`);

    // Generate CSRF state token
    const state = crypto.randomBytes(32).toString('hex');
    this.stateStore.set(state, { provider: providerName, redirectTo });

    // Auto-expire state after 10 minutes
    setTimeout(() => this.stateStore.delete(state), 10 * 60 * 1000);

    const params = new URLSearchParams({
      client_id: provider.clientId,
      redirect_uri: this.getCallbackUrl(providerName),
      response_type: 'code',
      scope: provider.scopes.join(' '),
      state,
      access_type: 'offline', // For refresh tokens (Google)
      prompt: 'consent',
    });

    return `${provider.authorizationUrl}?${params}`;
  }

  async handleCallback(
    providerName: string,
    code: string,
    state: string
  ): Promise<{ user: OAuthUserInfo; redirectTo?: string }> {
    // Verify state
    const stateData = this.stateStore.get(state);
    if (!stateData || stateData.provider !== providerName) {
      throw new Error('Invalid state parameter');
    }
    this.stateStore.delete(state);

    const provider = providers[providerName];
    if (!provider) throw new Error(`Unknown provider: ${providerName}`);

    // Exchange code for tokens
    const tokens = await this.exchangeCode(provider, code);

    // Fetch user info
    const userInfo = await this.fetchUserInfo(provider, tokens.accessToken, providerName);

    return { user: userInfo, redirectTo: stateData.redirectTo };
  }

  private async exchangeCode(provider: OAuthProvider, code: string): Promise<OAuthTokens> {
    const response = await fetch(provider.tokenUrl, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        Accept: 'application/json',
      },
      body: new URLSearchParams({
        client_id: provider.clientId,
        client_secret: provider.clientSecret,
        code,
        grant_type: 'authorization_code',
        redirect_uri: this.getCallbackUrl(provider.name.toLowerCase()),
      }),
    });

    if (!response.ok) {
      throw new Error(`Token exchange failed: ${response.statusText}`);
    }

    const data = await response.json();

    return {
      accessToken: data.access_token,
      refreshToken: data.refresh_token,
      expiresIn: data.expires_in,
      tokenType: data.token_type,
    };
  }

  private async fetchUserInfo(
    provider: OAuthProvider,
    accessToken: string,
    providerName: string
  ): Promise<OAuthUserInfo> {
    const response = await fetch(provider.userInfoUrl, {
      headers: {
        Authorization: `Bearer ${accessToken}`,
        Accept: 'application/json',
      },
    });

    if (!response.ok) {
      throw new Error(`Failed to fetch user info: ${response.statusText}`);
    }

    const data = await response.json();

    // Normalize user info across providers
    return this.normalizeUserInfo(data, providerName);
  }

  private normalizeUserInfo(data: Record<string, unknown>, provider: string): OAuthUserInfo {
    switch (provider) {
      case 'google':
        return {
          id: data.id as string,
          email: data.email as string,
          name: data.name as string,
          picture: data.picture as string,
          provider: 'google',
        };
      case 'github':
        return {
          id: String(data.id),
          email: data.email as string,
          name: (data.name || data.login) as string,
          picture: data.avatar_url as string,
          provider: 'github',
        };
      default:
        throw new Error(`Unknown provider: ${provider}`);
    }
  }

  private getCallbackUrl(provider: string): string {
    return `${process.env.APP_URL}/auth/${provider}/callback`;
  }
}

export const oauthService = new OAuthService();
typescript
// oauth-service.ts
import crypto from 'crypto';
import { providers, OAuthProvider } from './oauth-config';

interface OAuthTokens {
  accessToken: string;
  refreshToken?: string;
  expiresIn?: number;
  tokenType: string;
}

interface OAuthUserInfo {
  id: string;
  email: string;
  name?: string;
  picture?: string;
  provider: string;
}

class OAuthService {
  private stateStore = new Map<string, { provider: string; redirectTo?: string }>();

  generateAuthUrl(providerName: string, redirectTo?: string): string {
    const provider = providers[providerName];
    if (!provider) throw new Error(`Unknown provider: ${providerName}`);

    // Generate CSRF state token
    const state = crypto.randomBytes(32).toString('hex');
    this.stateStore.set(state, { provider: providerName, redirectTo });

    // Auto-expire state after 10 minutes
    setTimeout(() => this.stateStore.delete(state), 10 * 60 * 1000);

    const params = new URLSearchParams({
      client_id: provider.clientId,
      redirect_uri: this.getCallbackUrl(providerName),
      response_type: 'code',
      scope: provider.scopes.join(' '),
      state,
      access_type: 'offline', // For refresh tokens (Google)
      prompt: 'consent',
    });

    return `${provider.authorizationUrl}?${params}`;
  }

  async handleCallback(
    providerName: string,
    code: string,
    state: string
  ): Promise<{ user: OAuthUserInfo; redirectTo?: string }> {
    // Verify state
    const stateData = this.stateStore.get(state);
    if (!stateData || stateData.provider !== providerName) {
      throw new Error('Invalid state parameter');
    }
    this.stateStore.delete(state);

    const provider = providers[providerName];
    if (!provider) throw new Error(`Unknown provider: ${providerName}`);

    // Exchange code for tokens
    const tokens = await this.exchangeCode(provider, code);

    // Fetch user info
    const userInfo = await this.fetchUserInfo(provider, tokens.accessToken, providerName);

    return { user: userInfo, redirectTo: stateData.redirectTo };
  }

  private async exchangeCode(provider: OAuthProvider, code: string): Promise<OAuthTokens> {
    const response = await fetch(provider.tokenUrl, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        Accept: 'application/json',
      },
      body: new URLSearchParams({
        client_id: provider.clientId,
        client_secret: provider.clientSecret,
        code,
        grant_type: 'authorization_code',
        redirect_uri: this.getCallbackUrl(provider.name.toLowerCase()),
      }),
    });

    if (!response.ok) {
      throw new Error(`Token exchange failed: ${response.statusText}`);
    }

    const data = await response.json();

    return {
      accessToken: data.access_token,
      refreshToken: data.refresh_token,
      expiresIn: data.expires_in,
      tokenType: data.token_type,
    };
  }

  private async fetchUserInfo(
    provider: OAuthProvider,
    accessToken: string,
    providerName: string
  ): Promise<OAuthUserInfo> {
    const response = await fetch(provider.userInfoUrl, {
      headers: {
        Authorization: `Bearer ${accessToken}`,
        Accept: 'application/json',
      },
    });

    if (!response.ok) {
      throw new Error(`Failed to fetch user info: ${response.statusText}`);
    }

    const data = await response.json();

    // Normalize user info across providers
    return this.normalizeUserInfo(data, providerName);
  }

  private normalizeUserInfo(data: Record<string, unknown>, provider: string): OAuthUserInfo {
    switch (provider) {
      case 'google':
        return {
          id: data.id as string,
          email: data.email as string,
          name: data.name as string,
          picture: data.picture as string,
          provider: 'google',
        };
      case 'github':
        return {
          id: String(data.id),
          email: data.email as string,
          name: (data.name || data.login) as string,
          picture: data.avatar_url as string,
          provider: 'github',
        };
      default:
        throw new Error(`Unknown provider: ${provider}`);
    }
  }

  private getCallbackUrl(provider: string): string {
    return `${process.env.APP_URL}/auth/${provider}/callback`;
  }
}

export const oauthService = new OAuthService();

Express Routes

Express 路由

typescript
// oauth-routes.ts
import { Router, Request, Response } from 'express';
import { oauthService } from './oauth-service';
import { userService } from './user-service';
import { sessionService } from './session-service';

const router = Router();

// Initiate OAuth flow
router.get('/auth/:provider', (req: Request, res: Response) => {
  const { provider } = req.params;
  const { redirect } = req.query;

  try {
    const authUrl = oauthService.generateAuthUrl(provider, redirect as string);
    res.redirect(authUrl);
  } catch (error) {
    res.status(400).json({ error: (error as Error).message });
  }
});

// OAuth callback
router.get('/auth/:provider/callback', async (req: Request, res: Response) => {
  const { provider } = req.params;
  const { code, state, error } = req.query;

  if (error) {
    return res.redirect(`/login?error=${error}`);
  }

  if (!code || !state) {
    return res.redirect('/login?error=missing_params');
  }

  try {
    const { user: oauthUser, redirectTo } = await oauthService.handleCallback(
      provider,
      code as string,
      state as string
    );

    // Find or create user
    let user = await userService.findByOAuthId(provider, oauthUser.id);

    if (!user) {
      // Check if email already exists
      const existingUser = await userService.findByEmail(oauthUser.email);

      if (existingUser) {
        // Link OAuth to existing account
        user = await userService.linkOAuthAccount(existingUser.id, {
          provider,
          providerId: oauthUser.id,
          email: oauthUser.email,
        });
      } else {
        // Create new user
        user = await userService.createFromOAuth({
          email: oauthUser.email,
          name: oauthUser.name,
          picture: oauthUser.picture,
          provider,
          providerId: oauthUser.id,
        });
      }
    }

    // Create session
    const session = await sessionService.create(user.id);
    res.cookie('session', session.token, {
      httpOnly: true,
      secure: process.env.NODE_ENV === 'production',
      sameSite: 'lax',
      maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days
    });

    res.redirect(redirectTo || '/dashboard');
  } catch (error) {
    console.error('OAuth callback error:', error);
    res.redirect('/login?error=oauth_failed');
  }
});

export { router as oauthRoutes };
typescript
// oauth-routes.ts
import { Router, Request, Response } from 'express';
import { oauthService } from './oauth-service';
import { userService } from './user-service';
import { sessionService } from './session-service';

const router = Router();

// Initiate OAuth flow
router.get('/auth/:provider', (req: Request, res: Response) => {
  const { provider } = req.params;
  const { redirect } = req.query;

  try {
    const authUrl = oauthService.generateAuthUrl(provider, redirect as string);
    res.redirect(authUrl);
  } catch (error) {
    res.status(400).json({ error: (error as Error).message });
  }
});

// OAuth callback
router.get('/auth/:provider/callback', async (req: Request, res: Response) => {
  const { provider } = req.params;
  const { code, state, error } = req.query;

  if (error) {
    return res.redirect(`/login?error=${error}`);
  }

  if (!code || !state) {
    return res.redirect('/login?error=missing_params');
  }

  try {
    const { user: oauthUser, redirectTo } = await oauthService.handleCallback(
      provider,
      code as string,
      state as string
    );

    // Find or create user
    let user = await userService.findByOAuthId(provider, oauthUser.id);

    if (!user) {
      // Check if email already exists
      const existingUser = await userService.findByEmail(oauthUser.email);

      if (existingUser) {
        // Link OAuth to existing account
        user = await userService.linkOAuthAccount(existingUser.id, {
          provider,
          providerId: oauthUser.id,
          email: oauthUser.email,
        });
      } else {
        // Create new user
        user = await userService.createFromOAuth({
          email: oauthUser.email,
          name: oauthUser.name,
          picture: oauthUser.picture,
          provider,
          providerId: oauthUser.id,
        });
      }
    }

    // Create session
    const session = await sessionService.create(user.id);
    res.cookie('session', session.token, {
      httpOnly: true,
      secure: process.env.NODE_ENV === 'production',
      sameSite: 'lax',
      maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days
    });

    res.redirect(redirectTo || '/dashboard');
  } catch (error) {
    console.error('OAuth callback error:', error);
    res.redirect('/login?error=oauth_failed');
  }
});

export { router as oauthRoutes };

User Service (Account Linking)

用户服务（账号关联）

typescript
// user-service.ts
interface User {
  id: string;
  email: string;
  name?: string;
  picture?: string;
  oauthAccounts: OAuthAccount[];
}

interface OAuthAccount {
  provider: string;
  providerId: string;
  email: string;
}

class UserService {
  async findByOAuthId(provider: string, providerId: string): Promise<User | null> {
    // Find user by OAuth provider ID
    return db.user.findFirst({
      where: {
        oauthAccounts: {
          some: { provider, providerId },
        },
      },
      include: { oauthAccounts: true },
    });
  }

  async findByEmail(email: string): Promise<User | null> {
    return db.user.findUnique({
      where: { email },
      include: { oauthAccounts: true },
    });
  }

  async createFromOAuth(data: {
    email: string;
    name?: string;
    picture?: string;
    provider: string;
    providerId: string;
  }): Promise<User> {
    return db.user.create({
      data: {
        email: data.email,
        name: data.name,
        picture: data.picture,
        oauthAccounts: {
          create: {
            provider: data.provider,
            providerId: data.providerId,
            email: data.email,
          },
        },
      },
      include: { oauthAccounts: true },
    });
  }

  async linkOAuthAccount(userId: string, account: OAuthAccount): Promise<User> {
    return db.user.update({
      where: { id: userId },
      data: {
        oauthAccounts: {
          create: account,
        },
      },
      include: { oauthAccounts: true },
    });
  }

  async unlinkOAuthAccount(userId: string, provider: string): Promise<void> {
    const user = await this.findById(userId);
    
    // Ensure user has another way to login
    if (user.oauthAccounts.length <= 1 && !user.passwordHash) {
      throw new Error('Cannot unlink last authentication method');
    }

    await db.oauthAccount.deleteMany({
      where: { userId, provider },
    });
  }
}

export const userService = new UserService();
typescript
// user-service.ts
interface User {
  id: string;
  email: string;
  name?: string;
  picture?: string;
  oauthAccounts: OAuthAccount[];
}

interface OAuthAccount {
  provider: string;
  providerId: string;
  email: string;
}

class UserService {
  async findByOAuthId(provider: string, providerId: string): Promise<User | null> {
    // Find user by OAuth provider ID
    return db.user.findFirst({
      where: {
        oauthAccounts: {
          some: { provider, providerId },
        },
      },
      include: { oauthAccounts: true },
    });
  }

  async findByEmail(email: string): Promise<User | null> {
    return db.user.findUnique({
      where: { email },
      include: { oauthAccounts: true },
    });
  }

  async createFromOAuth(data: {
    email: string;
    name?: string;
    picture?: string;
    provider: string;
    providerId: string;
  }): Promise<User> {
    return db.user.create({
      data: {
        email: data.email,
        name: data.name,
        picture: data.picture,
        oauthAccounts: {
          create: {
            provider: data.provider,
            providerId: data.providerId,
            email: data.email,
          },
        },
      },
      include: { oauthAccounts: true },
    });
  }

  async linkOAuthAccount(userId: string, account: OAuthAccount): Promise<User> {
    return db.user.update({
      where: { id: userId },
      data: {
        oauthAccounts: {
          create: account,
        },
      },
      include: { oauthAccounts: true },
    });
  }

  async unlinkOAuthAccount(userId: string, provider: string): Promise<void> {
    const user = await this.findById(userId);
    
    // Ensure user has another way to login
    if (user.oauthAccounts.length <= 1 && !user.passwordHash) {
      throw new Error('Cannot unlink last authentication method');
    }

    await db.oauthAccount.deleteMany({
      where: { userId, provider },
    });
  }
}

export const userService = new UserService();

Python Implementation

Python 实现

python
undefined
python
undefined

oauth_service.py

oauth_service.py

import secrets import httpx from dataclasses import dataclass from typing import Optional from urllib.parse import urlencode
@dataclass class OAuthProvider: name: str client_id: str client_secret: str authorization_url: str token_url: str user_info_url: str scopes: list[str]
PROVIDERS = { "google": OAuthProvider( name="Google", client_id=os.environ["GOOGLE_CLIENT_ID"], client_secret=os.environ["GOOGLE_CLIENT_SECRET"], authorization_url="https://accounts.google.com/o/oauth2/v2/auth", token_url="https://oauth2.googleapis.com/token", user_info_url="https://www.googleapis.com/oauth2/v2/userinfo", scopes=["openid", "email", "profile"], ), "github": OAuthProvider( name="GitHub", client_id=os.environ["GITHUB_CLIENT_ID"], client_secret=os.environ["GITHUB_CLIENT_SECRET"], authorization_url="https://github.com/login/oauth/authorize", token_url="https://github.com/login/oauth/access_token", user_info_url="https://api.github.com/user", scopes=["read:user", "user:email"], ), }
class OAuthService: def init(self): self._state_store: dict[str, dict] = {}
def generate_auth_url(self, provider_name: str, redirect_to: Optional[str] = None) -> str:
    provider = PROVIDERS.get(provider_name)
    if not provider:
        raise ValueError(f"Unknown provider: {provider_name}")

    state = secrets.token_hex(32)
    self._state_store[state] = {"provider": provider_name, "redirect_to": redirect_to}

    params = {
        "client_id": provider.client_id,
        "redirect_uri": self._get_callback_url(provider_name),
        "response_type": "code",
        "scope": " ".join(provider.scopes),
        "state": state,
    }

    return f"{provider.authorization_url}?{urlencode(params)}"

async def handle_callback(self, provider_name: str, code: str, state: str):
    state_data = self._state_store.pop(state, None)
    if not state_data or state_data["provider"] != provider_name:
        raise ValueError("Invalid state")

    provider = PROVIDERS[provider_name]
    tokens = await self._exchange_code(provider, code)
    user_info = await self._fetch_user_info(provider, tokens["access_token"], provider_name)

    return {"user": user_info, "redirect_to": state_data.get("redirect_to")}

async def _exchange_code(self, provider: OAuthProvider, code: str) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.post(
            provider.token_url,
            data={
                "client_id": provider.client_id,
                "client_secret": provider.client_secret,
                "code": code,
                "grant_type": "authorization_code",
                "redirect_uri": self._get_callback_url(provider.name.lower()),
            },
            headers={"Accept": "application/json"},
        )
        response.raise_for_status()
        return response.json()

async def _fetch_user_info(self, provider: OAuthProvider, access_token: str, provider_name: str) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.get(
            provider.user_info_url,
            headers={"Authorization": f"Bearer {access_token}"},
        )
        response.raise_for_status()
        data = response.json()

    return self._normalize_user_info(data, provider_name)

def _normalize_user_info(self, data: dict, provider: str) -> dict:
    if provider == "google":
        return {
            "id": data["id"],
            "email": data["email"],
            "name": data.get("name"),
            "picture": data.get("picture"),
            "provider": "google",
        }
    elif provider == "github":
        return {
            "id": str(data["id"]),
            "email": data["email"],
            "name": data.get("name") or data.get("login"),
            "picture": data.get("avatar_url"),
            "provider": "github",
        }
    raise ValueError(f"Unknown provider: {provider}")

def _get_callback_url(self, provider: str) -> str:
    return f"{os.environ['APP_URL']}/auth/{provider}/callback"
oauth_service = OAuthService()
undefined
import secrets import httpx from dataclasses import dataclass from typing import Optional from urllib.parse import urlencode
@dataclass class OAuthProvider: name: str client_id: str client_secret: str authorization_url: str token_url: str user_info_url: str scopes: list[str]
PROVIDERS = { "google": OAuthProvider( name="Google", client_id=os.environ["GOOGLE_CLIENT_ID"], client_secret=os.environ["GOOGLE_CLIENT_SECRET"], authorization_url="https://accounts.google.com/o/oauth2/v2/auth", token_url="https://oauth2.googleapis.com/token", user_info_url="https://www.googleapis.com/oauth2/v2/userinfo", scopes=["openid", "email", "profile"], ), "github": OAuthProvider( name="GitHub", client_id=os.environ["GITHUB_CLIENT_ID"], client_secret=os.environ["GITHUB_CLIENT_SECRET"], authorization_url="https://github.com/login/oauth/authorize", token_url="https://github.com/login/oauth/access_token", user_info_url="https://api.github.com/user", scopes=["read:user", "user:email"], ), }
class OAuthService: def init(self): self._state_store: dict[str, dict] = {}
def generate_auth_url(self, provider_name: str, redirect_to: Optional[str] = None) -> str:
    provider = PROVIDERS.get(provider_name)
    if not provider:
        raise ValueError(f"Unknown provider: {provider_name}")

    state = secrets.token_hex(32)
    self._state_store[state] = {"provider": provider_name, "redirect_to": redirect_to}

    params = {
        "client_id": provider.client_id,
        "redirect_uri": self._get_callback_url(provider_name),
        "response_type": "code",
        "scope": " ".join(provider.scopes),
        "state": state,
    }

    return f"{provider.authorization_url}?{urlencode(params)}"

async def handle_callback(self, provider_name: str, code: str, state: str):
    state_data = self._state_store.pop(state, None)
    if not state_data or state_data["provider"] != provider_name:
        raise ValueError("Invalid state")

    provider = PROVIDERS[provider_name]
    tokens = await self._exchange_code(provider, code)
    user_info = await self._fetch_user_info(provider, tokens["access_token"], provider_name)

    return {"user": user_info, "redirect_to": state_data.get("redirect_to")}

async def _exchange_code(self, provider: OAuthProvider, code: str) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.post(
            provider.token_url,
            data={
                "client_id": provider.client_id,
                "client_secret": provider.client_secret,
                "code": code,
                "grant_type": "authorization_code",
                "redirect_uri": self._get_callback_url(provider.name.lower()),
            },
            headers={"Accept": "application/json"},
        )
        response.raise_for_status()
        return response.json()

async def _fetch_user_info(self, provider: OAuthProvider, access_token: str, provider_name: str) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.get(
            provider.user_info_url,
            headers={"Authorization": f"Bearer {access_token}"},
        )
        response.raise_for_status()
        data = response.json()

    return self._normalize_user_info(data, provider_name)

def _normalize_user_info(self, data: dict, provider: str) -> dict:
    if provider == "google":
        return {
            "id": data["id"],
            "email": data["email"],
            "name": data.get("name"),
            "picture": data.get("picture"),
            "provider": "google",
        }
    elif provider == "github":
        return {
            "id": str(data["id"]),
            "email": data["email"],
            "name": data.get("name") or data.get("login"),
            "picture": data.get("avatar_url"),
            "provider": "github",
        }
    raise ValueError(f"Unknown provider: {provider}")

def _get_callback_url(self, provider: str) -> str:
    return f"{os.environ['APP_URL']}/auth/{provider}/callback"
oauth_service = OAuthService()
undefined

Database Schema

数据库 Schema

sql
-- Users table
CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email VARCHAR(255) UNIQUE NOT NULL,
  name VARCHAR(255),
  picture TEXT,
  password_hash VARCHAR(255), -- NULL for OAuth-only users
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

-- OAuth accounts (one user can have multiple)
CREATE TABLE oauth_accounts (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES users(id) ON DELETE CASCADE,
  provider VARCHAR(50) NOT NULL,
  provider_id VARCHAR(255) NOT NULL,
  email VARCHAR(255),
  access_token TEXT,
  refresh_token TEXT,
  expires_at TIMESTAMP,
  created_at TIMESTAMP DEFAULT NOW(),
  UNIQUE(provider, provider_id)
);

CREATE INDEX idx_oauth_accounts_user ON oauth_accounts(user_id);
CREATE INDEX idx_oauth_accounts_provider ON oauth_accounts(provider, provider_id);
sql
-- Users table
CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email VARCHAR(255) UNIQUE NOT NULL,
  name VARCHAR(255),
  picture TEXT,
  password_hash VARCHAR(255), -- NULL for OAuth-only users
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

-- OAuth accounts (one user can have multiple)
CREATE TABLE oauth_accounts (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES users(id) ON DELETE CASCADE,
  provider VARCHAR(50) NOT NULL,
  provider_id VARCHAR(255) NOT NULL,
  email VARCHAR(255),
  access_token TEXT,
  refresh_token TEXT,
  expires_at TIMESTAMP,
  created_at TIMESTAMP DEFAULT NOW(),
  UNIQUE(provider, provider_id)
);

CREATE INDEX idx_oauth_accounts_user ON oauth_accounts(user_id);
CREATE INDEX idx_oauth_accounts_provider ON oauth_accounts(provider, provider_id);

Frontend Integration

前端集成

typescript
// Login component
function LoginPage() {
  return (
    <div className="login-options">
      <a href="/auth/google" className="oauth-button google">
        <GoogleIcon /> Sign in with Google
      </a>
      <a href="/auth/github" className="oauth-button github">
        <GitHubIcon /> Sign in with GitHub
      </a>
      <div className="divider">or</div>
      <form className="email-login">
        {/* Email/password form */}
      </form>
    </div>
  );
}
typescript
// Login component
function LoginPage() {
  return (
    <div className="login-options">
      <a href="/auth/google" className="oauth-button google">
        <GoogleIcon /> Sign in with Google
      </a>
      <a href="/auth/github" className="oauth-button github">
        <GitHubIcon /> Sign in with GitHub
      </a>
      <div className="divider">or</div>
      <form className="email-login">
        {/* Email/password form */}
      </form>
    </div>
  );
}

Security Considerations

安全注意事项

  1. Always verify state parameter - Prevents CSRF attacks
  2. Use HTTPS in production - Tokens are sensitive
  3. Validate email ownership - Some providers don't verify emails
  4. Handle account linking carefully - Prevent account takeover
  5. Store tokens securely - Encrypt refresh tokens at rest
  1. 务必验证state参数 - 防止CSRF攻击
  2. 生产环境使用HTTPS - 令牌属于敏感信息
  3. 验证邮箱所有权 - 部分服务商不会验证邮箱有效性
  4. 谨慎处理账号关联 - 防止账号被劫持
  5. 安全存储令牌 - 静态存储时加密刷新令牌

Common Mistakes

常见错误

  • Not validating state parameter
  • Storing access tokens in localStorage
  • Not handling token refresh
  • Allowing unverified email linking
  • Missing error handling for revoked tokens
  • 未验证state参数
  • 在localStorage中存储访问令牌
  • 未处理令牌刷新
  • 允许未验证邮箱的关联
  • 缺少对已撤销令牌的错误处理