OAuth Social Login
Add "Sign in with Google/GitHub" to your app.
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 │
└─────────────────────────────────────────────────────┘TypeScript Implementation
OAuth Configuration
// 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-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
// 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)
// 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
# 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()Database Schema
-- 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
// 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
- Always verify state parameter - Prevents CSRF attacks
- Use HTTPS in production - Tokens are sensitive
- Validate email ownership - Some providers don't verify emails
- Handle account linking carefully - Prevent account takeover
- Store tokens securely - Encrypt refresh tokens at rest
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