OAuth2 & Social Login

The Problem

Users hate creating new accounts. Social login (“Sign in with Google/GitHub/Apple”) reduces friction by leveraging existing identity providers. OAuth 2.0 is the standard protocol enabling this — but it’s a framework with many flows, grant types, and security considerations. You must implement the authorization code flow securely, handle token lifecycle (access tokens, refresh tokens, ID tokens), support multiple providers, link social accounts to existing users, and protect against attacks like CSRF, token leakage, and open redirectors.

Architectural Approaches

Architecture

Loading diagram...

Key Components

Data Model

Loading diagram...

Authorization Code Flow Step by Step

Step 1 — Authorization Request: User clicks “Sign in with Google.” Your backend generates an authorization URL:

https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=https://yourapp.com/auth/callback&response_type=code&scope=openid email profile&state=RANDOM_STATE_TOKEN&code_challenge=SHA256_HASH&code_challenge_method=S256

Step 2 — User Consent: Google shows a consent screen. User approves.

Step 3 — Callback: Google redirects to your callback URL: https://yourapp.com/auth/callback?code=AUTH_CODE&state=RANDOM_STATE_TOKEN

Step 4 — Validate State: Verify the state parameter matches what you stored. This prevents CSRF attacks.

Step 5 — Exchange Code: POST to Google’s token endpoint with the authorization code, client secret, and PKCE code verifier. Receive: access_token, refresh_token, id_token.

Step 6 — Verify ID Token: Decode and verify the JWT ID token: check signature (using Google’s public keys from JWKS endpoint), issuer, audience, expiry, and nonce.

Step 7 — Create Session: Extract user identity from the ID token (sub, email, name). Find or create the user in your database. Create an application session and redirect to the app.

Loading diagram...

Token Security and Storage

OAuth tokens are sensitive credentials that must be handled carefully.

Access tokens: Short-lived (15 min - 1 hour). Used to call the provider’s API on behalf of the user. Store server-side only, encrypted at rest. Never expose to the browser unless absolutely necessary.

Refresh tokens: Long-lived (days to months). Used to obtain new access tokens without user interaction. Store server-side, encrypted, with strict access controls. Refresh token rotation: each time you use a refresh token, the provider issues a new one and invalidates the old one.

ID tokens: JWTs containing user identity claims. Validate signature, issuer, audience, and expiry on every use. Cache the provider’s JWKS (public keys) for signature verification. Do NOT use the ID token as an API access token.

Session tokens (your app): After OAuth completes, issue your own session token. Options:

• HTTP-only cookie: Most secure for web apps. Set Secure, SameSite=Lax, HttpOnly flags.
• JWT in Authorization header: Better for API-first apps. Short expiry (15 min) with refresh mechanism.

Never store tokens in: localStorage (XSS risk), URL parameters (logged in server logs/history), or unencrypted database fields.

Token revocation: When a user disconnects a social account or your app detects suspicious activity, revoke the refresh token by calling the provider’s revocation endpoint.

Account Linking and Edge Cases

Mapping social identities to internal accounts has subtle edge cases.

First-time login: No matching social account or email exists. Create a new user and link the social account. Simple case.

Returning user: Social account already linked. Find the user by (provider, provider_user_id). Log them in.

Email collision: User signs up with Google (alice@example.com), later tries to log in with GitHub (also alice@example.com). Options:

• Auto-link by email: If the email is verified by both providers, assume same person and link. Convenient but risky if one provider doesn’t verify emails.
• Prompt to link: Show “An account with this email already exists. Log in with Google to link your GitHub account.” Safer but more friction.
• Separate accounts: Create a new account. Safest but can confuse users.

Multiple providers: A user may link Google, GitHub, and Apple to one account. Store all social accounts and allow login via any of them. The user should be able to see and manage linked providers in their settings.

Provider-specific quirks:

• Apple: Uses “private relay” emails (randomhash@privaterelay.appleid.com). Store the real email from the first authentication — Apple only sends it once.
• GitHub: Email may be private. Requires additional API call to /user/emails endpoint.
• Google: Always returns verified email. Most reliable provider for email-based linking.

Real-World Examples

Architectural Tradeoffs

# Learn the System Design of: OAuth2 & Social Login

You are an expert software architect and teacher. I want to understand oauth2 & social login as a practical system design capability. (Authorization code flow, token refresh, and provider federation for third-party authentication).

Use the following architectural guide as a learning reference. Avoid one-size-fits-all recommendations. Keep assumptions, costs, and tradeoffs explicit.

---

import { Mermaid, ComponentList, ComponentCard, ApproachList, Approach, Example, Tradeoff } from '@/components/mdx';

## The Problem

Users hate creating new accounts. Social login ("Sign in with Google/GitHub/Apple") reduces friction by leveraging existing identity providers. OAuth 2.0 is the standard protocol enabling this — but it's a framework with many flows, grant types, and security considerations. You must implement the authorization code flow securely, handle token lifecycle (access tokens, refresh tokens, ID tokens), support multiple providers, link social accounts to existing users, and protect against attacks like CSRF, token leakage, and open redirectors.

## Architectural Approaches

<ApproachList>
<Approach
  name="Authorization Code Flow with PKCE"
  pros={[
    'Most secure flow — tokens never exposed in browser URL',
    'PKCE protects against code interception (critical for mobile/SPA)',
    'Supports refresh tokens for long-lived sessions',
    'Works for all client types (server-side, SPA, mobile)',
  ]}
  cons={[
    'More round-trips than implicit flow (code exchange step)',
    'Requires server-side component for token exchange (or PKCE for public clients)',
    'Must handle redirect URI validation carefully',
    'Each provider has slightly different implementation quirks',
  ]}
>
The recommended OAuth 2.0 flow for all clients (web, mobile, SPA). The client redirects the user to the provider's authorization endpoint. After consent, the provider redirects back with a short-lived **authorization code**. The...

[Full prompt copied to clipboard]