Chapter 5 — OAuth & Social Login

The why

OAuth 2.0 is the protocol behind every "Sign in with Google/GitHub/Apple" button. It's also behind API authorization for Stripe, GitHub, and thousands of other services. Understanding OAuth deeply means you can implement social login securely and integrate with any third-party API.

Core concepts

OAuth 2.0 vs OpenID Connect (OIDC)

OAuth 2.0 is an authorization framework. It answers: "Can this app access my data?" OpenID Connect (OIDC) is an authentication layer built on top of OAuth 2.0. It answers: "Who is this user?"

Every "Sign in with Google" button uses OIDC. Every "Connect your GitHub account to our app" uses OAuth 2.0.

The OAuth 2.0 Authorization Code Flow (with PKCE)

The Authorization Code flow is the only flow you should use for server-side web apps. It involves three parties: the User, your App, and the Authorization Server (Google/GitHub).

1. User clicks "Sign in with Google"
2. Your app redirects to Google's authorization endpoint:
   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%20email%20profile&
     code_challenge=PKCE_CHALLENGE&           ← PKCE
     code_challenge_method=S256&
     state=RANDOM_STATE                         ← CSRF protection
 
3. User authenticates with Google, approves scopes
4. Google redirects back to your app with an authorization code:
   https://yourapp.com/auth/callback?code=AUTH_CODE&state=RANDOM_STATE
 
5. Your server exchanges the code for tokens (server-to-server):
   POST https://oauth2.googleapis.com/token
   Body: { code, client_id, client_secret, code_verifier=PKCE_VERIFIER, grant_type='authorization_code' }
 
6. Google returns: { access_token, id_token, refresh_token }
7. Your server validates the ID token, extracts user info, creates/updates user in DB
8. Your server creates a session or JWT for the user

// Step 1: Redirect user to Google
const crypto = require('crypto');
 
function generatePKCE() {
  const verifier = crypto.randomBytes(32).toString('base64url');
  const challenge = crypto

PKCE — why it's not optional

PKCE (Proof Key for Code Exchange, pronounced "pixie") prevents authorization code interception attacks. Without PKCE:

1. Attacker's malicious app initiates OAuth flow → gets authorization code
2. Attacker intercepts the redirect to your app (via custom URL scheme on mobile, or
   a malicious browser extension)
3. Attacker exchanges the stolen code for tokens → your app gets nothing
4. The user's account is now linked to the attacker's session

PKCE works because the code verifier is known only to the original requester. Even if an attacker intercepts the authorization code, they can't exchange it for tokens without the code verifier.

OAuth scopes — the principle of least privilege

Scopes define what the access token can do. Always request the minimum:

// ❌ Over-permissioned
scope: 'https://www.googleapis.com/auth/drive' // Full access to all Drive files
 
// ✅ Least privilege
scope: 'https://www.googleapis.com/auth/drive.file' // Only files created by this app

For social login (OIDC), you typically need only: openid email profile. Don't request drive, calendar, or other scopes unless your app genuinely needs them. Every additional scope is additional risk if tokens are compromised.

Real-world example: How Notion implements OAuth

Notion uses OAuth 2.0 for its API integrations and social login. Key design decisions:

1. Separate OAuth clients for each integration. Slack, Google Calendar, GitHub — each has its own client ID and secret, each gets its own set of scopes.
2. Refresh token rotation. Notion rotates refresh tokens on every use, similar to JWT refresh token rotation. If a refresh token is reused, all tokens are revoked.
3. Scoped access to workspaces. When a user authorizes a Notion integration, they select which workspace(s) to grant access to — not all workspaces by default.

Common mistakes

Production notes

• Use a well-known OAuth library. openid-client (Node.js), Passport.js strategies, or NextAuth.js. They handle PKCE, state validation, token exchange, and ID token verification correctly.
• Store refresh tokens securely. Refresh tokens are long-lived credentials. Store them encrypted in the database (AES-256-GCM) or in a secrets manager.
• Monitor OAuth failure rates. A spike in failed token exchanges might indicate a misconfiguration or an attack.

Performance notes

• OAuth flows involve 2–3 HTTP round trips (redirect to provider, callback exchange, potentially userinfo endpoint). Total: 500ms–2s. This is fine for login (once per session).
• Cache provider JWKS. The JSON Web Key Set (public keys for ID token verification) should be cached with a TTL of 1 hour. Don't fetch it on every login.

Security notes

• Validate the iss (issuer) claim. Ensures the ID token came from the expected provider (Google, GitHub), not a malicious one.
• Validate the aud (audience) claim. Ensures the ID token was issued for your specific client ID, not a different application.
• Use the nonce parameter for replay protection. Include a random nonce in the auth request, validate it in the ID token response.

Exercises

Beginner

1. Register a Google OAuth application in the Google Cloud Console. Implement the authorization code flow (without PKCE initially). Successfully retrieve user info from Google.
2. Add PKCE to your implementation. Test that the flow still works. Explain what PKCE prevents.

Intermediate

1. Add GitHub OAuth in addition to Google. Let users choose which provider to sign in with. Merge accounts that share the same email.
2. Implement refresh token handling: store the refresh token, use it to get new access tokens when the old one expires, handle refresh token rotation.

Advanced

1. Build a multi-provider OAuth abstraction: a single /auth/:provider route that works with Google, GitHub, and Apple using a unified interface. Each provider implements getAuthorizationUrl(), exchangeCode(), getUserInfo().
2. Implement device authorization flow for TV/CLI apps where the user authorizes on their phone and the device polls for completion.

Interview questions

Beginner

1. What's the difference between OAuth 2.0 and OpenID Connect? OAuth 2.0 is for authorization (granting access to resources). OpenID Connect is a layer on top of OAuth 2.0 for authentication (verifying identity). OIDC adds an ID token (JWT) that contains user identity claims.

2. What is an OAuth scope? A permission string that specifies what access the client is requesting. Example: email profile grants access to the user's email and profile information. Scopes implement the principle of least privilege.

3. Why can't you put the OAuth client secret in frontend code? Anyone can view frontend source code. If the client secret is exposed, an attacker can impersonate your application and obtain tokens on behalf of your users.

Senior

4. Explain the OAuth Authorization Code flow with PKCE. (1) Client generates a code verifier and challenge (SHA-256 hashed verifier). (2) Client redirects user to authorization server with code challenge. (3) User authenticates and approves. (4) Authorization server redirects back with an authorization code. (5) Client exchanges the code + code verifier for tokens. (6) Authorization server validates the verifier against the challenge — rejects if mismatch. PKCE ensures that even if the authorization code is intercepted, the attacker cannot exchange it for tokens without the verifier.

5. What is the state parameter and why is it required? A random value generated by the client and validated on callback. It prevents CSRF attacks where an attacker initiates an OAuth flow and tricks the victim into completing it, linking the attacker's social account to the victim's app account. The state ties the callback to the original request.

6. How do you handle account linking when a user signs in with multiple OAuth providers? Match by verified email — if the email from Google matches the email from GitHub, link the accounts to the same user record. Store each provider's ID in a separate table (user_oauth_accounts with provider + provider_user_id). Always require email verification from the provider before trusting the email for linking.

Summary

OAuth 2.0 is the standard for delegated authorization. OIDC extends it for authentication ("Sign in with..."). The authorization code flow with PKCE is the only flow you should implement for server-side web apps. Always validate the state parameter (CSRF protection) and the ID token claims (iss, aud, exp). Request minimum scopes. Use established libraries (Passport, NextAuth, openid-client) rather than implementing the protocol from scratch.

Quick recall

• OAuth 2.0 = authorization (access to resources). OIDC = authentication (who is this user?).
• Authorization Code flow + PKCE (mandatory). state parameter (CSRF protection).
• ID token (JWT) = user identity. Access token = permission to access resources.
• Validate iss, aud, exp on ID token. Request minimum scopes.
• Client secret stays server-side. Never in frontend code.
• Use Passport.js, NextAuth, or openid-client — don't implement OAuth from scratch.

Quiz

1. What does OIDC add on top of OAuth 2.0? An ID token (JWT) containing user identity claims — makes OAuth suitable for authentication ("Sign in with X").
2. What does PKCE prevent? Authorization code interception — an attacker who steals the authorization code cannot exchange it for tokens without the code verifier.
3. What is the state parameter for? CSRF protection — ties the OAuth callback to the original request.
4. What three claims should you always validate on an ID token? iss (issuer), aud (audience), exp (expiration).
5. Why shouldn't you hardcode the client secret in a mobile app? The APK/IPA can be decompiled. The secret is extractable. Use PKCE instead for public clients.
6. What scopes should you request for a simple social login? openid email profile — minimum needed for identity.
7. How do you link accounts when a user signs in with multiple OAuth providers? Match by verified email. Store each provider's ID in a separate table. Always verify email with the provider first.