OAuth 2.0 Complete Guide: Authorization Code, PKCE, OpenID Connect, JWT, and Security Best Practices

What Is OAuth 2.0 and Why Was It Created?

Before OAuth, delegating API access was painful. If you wanted a third-party app to access your Google Drive, you had to give it your Google username and password. The app had full access to your entire account, you could not revoke access without changing your password, and the third party could do anything a human could do.

OAuth 2.0 (RFC 6749, published 2012) solved this with a delegation model. Instead of sharing credentials, the user grants a third-party application a limited, scoped access token. The user approves specific permissions (scopes), the token expires automatically, and the user can revoke access at any time without changing their password.

OAuth 2.0 defines four roles: the Resource Owner (the user), the Client (the third-party application), the Authorization Server (the service that issues tokens, e.g., Google's auth server), and the Resource Server (the API holding the protected resources, e.g., Google Drive API). These roles communicate through a series of redirects and back-channel requests.

The key insight of OAuth 2.0 is that the user's credentials never reach the third-party application. The user authenticates directly with the Authorization Server (which they trust), and only the resulting token is handed to the client.

OAuth 2.0 vs OAuth 1.0 vs OpenID Connect

OAuth 1.0 (2007) required complex cryptographic request signing (HMAC-SHA1) for every API call. Every request had to include a timestamp, nonce, and signature computed from the request parameters and a shared secret. While secure, it was extremely difficult to implement correctly and was a poor developer experience.

OAuth 2.0 dropped mandatory request signing in favor of TLS (HTTPS) for transport security. This made implementation far simpler but introduced new complexity through the proliferation of grant types. OAuth 2.0 is a framework, not a protocol — implementations can vary significantly between providers.

OpenID Connect (OIDC) is a thin identity layer built on top of OAuth 2.0. Where OAuth 2.0 only handles authorization (can this app access this resource?), OIDC adds authentication (who is this user?). OIDC introduces the ID token — a JWT containing identity claims like name, email, and profile picture. If you need to know who the user is (not just that they authorized your app), use OIDC.

Quick Comparison

Key Concepts: Roles, Scopes, and Tokens

The Four OAuth 2.0 Roles

Every OAuth 2.0 interaction involves four roles. The Resource Owner is typically the end user who owns the data. The Client is the application requesting access (your web app, mobile app, or backend service). The Authorization Server issues access tokens after authenticating the resource owner and obtaining authorization. The Resource Server hosts the protected resources and validates access tokens on each request.

Scopes

Scopes define the permissions being requested. They are space-separated strings that the client requests and the user approves. Examples include read:user, repo, openid, email, and profile. Well-designed OAuth servers use fine-grained scopes so users can grant minimal necessary permissions. Always request only the scopes your application actually needs.

Token Types

OAuth 2.0 uses three types of tokens. Access tokens are short-lived credentials (typically 15-60 minutes) that the client includes in API requests. Refresh tokens are long-lived credentials (days to months) used to obtain new access tokens without user re-authentication. ID tokens (OIDC only) are JWTs containing user identity claims — they are for the client to read, not for sending to resource servers.

Grant Types: Which Flow Should You Use?

OAuth 2.0 defines multiple grant types (flows) for different client types and use cases. Picking the wrong grant type is the most common OAuth mistake.

Authorization Code Flow

The most widely used and most secure flow for server-side web applications. The client redirects the user to the Authorization Server, the user authenticates and consents, and the Authorization Server redirects back to the client with a short-lived authorization code. The client then exchanges this code for tokens via a direct server-to-server POST request. The access token never touches the browser.

Implicit Flow (Deprecated)

The Implicit flow was designed for SPAs that could not make server-side requests. The authorization server returned the access token directly in the URL fragment (#access_token=...). This was convenient but dangerous — tokens in URL fragments appear in browser history, referrer headers, and server logs. The Implicit flow is now deprecated by RFC 9700. Use Authorization Code + PKCE instead for all browser-based apps.

Client Credentials Flow

For machine-to-machine (M2M) communication where no user is involved. The client authenticates directly with the Authorization Server using its client_id and client_secret, and receives an access token. This is appropriate for backend services, cron jobs, microservice-to-microservice communication, and CI/CD pipelines. There is no redirect and no user interaction.

// Client Credentials Flow — Machine-to-Machine
// Node.js example

async function getM2MToken() {
  const response = await fetch('https://auth.example.com/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: process.env.CLIENT_ID,
      client_secret: process.env.CLIENT_SECRET,
      scope: 'read:reports write:data',
    }),
  });

  const { access_token, expires_in } = await response.json();

  // Cache the token until it expires (minus a buffer)
  tokenCache.set('m2m_token', {
    token: access_token,
    expiresAt: Date.now() + (expires_in - 60) * 1000, // 60s buffer
  });

  return access_token;
}

async function getCachedM2MToken() {
  const cached = tokenCache.get('m2m_token');
  if (cached && cached.expiresAt > Date.now()) {
    return cached.token;
  }
  return getM2MToken();
}

// Usage in a service call
async function fetchInternalData() {
  const token = await getCachedM2MToken();
  const res = await fetch('https://internal-api.example.com/reports', {
    headers: { Authorization: 'Bearer ' + token },
  });
  return res.json();
}

Device Authorization Flow

Designed for devices with limited input capabilities (smart TVs, gaming consoles, CLI tools). The device displays a short code and a URL. The user visits the URL on their phone or computer, enters the code, and authenticates. The device polls the Authorization Server until the user completes authentication. Used by tools like GitHub CLI and the AWS CLI.

Authorization Code + PKCE (Recommended for SPAs and Mobile)

PKCE (Proof Key for Code Exchange, pronounced "pixy") is an extension to the Authorization Code flow that eliminates the need for a client_secret for public clients. The client generates a random code_verifier, hashes it to produce a code_challenge, and sends the challenge with the authorization request. When exchanging the code for tokens, the client sends the original code_verifier. The server verifies that hash(code_verifier) == code_challenge, proving the token request came from the same client that started the flow.

// Authorization Code + PKCE — Complete Implementation
// Works for SPAs, mobile apps, and server-side apps

// Step 1: Generate PKCE code_verifier and code_challenge
function generateCodeVerifier() {
  const array = new Uint8Array(32);
  crypto.getRandomValues(array);
  return btoa(String.fromCharCode(...array))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=/g, '');
}

async function generateCodeChallenge(verifier) {
  const encoder = new TextEncoder();
  const data = encoder.encode(verifier);
  const digest = await crypto.subtle.digest('SHA-256', data);
  return btoa(String.fromCharCode(...new Uint8Array(digest)))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=/g, '');
}

// Step 2: Build authorization URL and redirect
async function startOAuthFlow() {
  const codeVerifier = generateCodeVerifier();
  const codeChallenge = await generateCodeChallenge(codeVerifier);
  const state = crypto.randomUUID(); // CSRF protection

  // Store verifier and state securely (sessionStorage is OK for this)
  sessionStorage.setItem('pkce_verifier', codeVerifier);
  sessionStorage.setItem('oauth_state', state);

  const params = new URLSearchParams({
    response_type: 'code',
    client_id: 'YOUR_CLIENT_ID',
    redirect_uri: 'https://yourapp.com/callback',
    scope: 'openid email profile',
    state,
    code_challenge: codeChallenge,
    code_challenge_method: 'S256',
  });

  window.location.href = 'https://accounts.google.com/o/oauth2/v2/auth?' + params;
}

// Step 3: Handle callback — exchange code for tokens
async function handleCallback() {
  const params = new URLSearchParams(window.location.search);
  const code = params.get('code');
  const state = params.get('state');
  const error = params.get('error');

  if (error) throw new Error('OAuth error: ' + error);

  // Validate state to prevent CSRF
  const storedState = sessionStorage.getItem('oauth_state');
  if (state !== storedState) throw new Error('State mismatch — possible CSRF attack');

  const codeVerifier = sessionStorage.getItem('pkce_verifier');
  sessionStorage.removeItem('pkce_verifier');
  sessionStorage.removeItem('oauth_state');

  // Exchange code for tokens
  const tokenResponse = await fetch('https://oauth2.googleapis.com/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      client_id: 'YOUR_CLIENT_ID',
      redirect_uri: 'https://yourapp.com/callback',
      code,
      code_verifier: codeVerifier,
    }),
  });

  const tokens = await tokenResponse.json();
  // tokens.access_token, tokens.refresh_token, tokens.id_token
  return tokens;
}

Access Tokens vs Refresh Tokens vs ID Tokens

Token Lifecycle and Refresh

// Token refresh with rotation — Express.js backend
const jwt = require('jsonwebtoken');

// In-memory store (use Redis or database in production)
const refreshTokenStore = new Map();

app.post('/auth/token/refresh', async (req, res) => {
  const { refresh_token } = req.body;
  if (!refresh_token) {
    return res.status(400).json({ error: 'refresh_token required' });
  }

  let payload;
  try {
    payload = jwt.verify(refresh_token, process.env.REFRESH_SECRET);
  } catch {
    return res.status(401).json({ error: 'Invalid refresh token' });
  }

  const stored = refreshTokenStore.get(payload.sub);
  if (!stored || stored.token !== refresh_token) {
    // Token reuse detected — invalidate family
    refreshTokenStore.delete(payload.sub);
    return res.status(401).json({ error: 'Refresh token reuse detected' });
  }

  // Issue new access token
  const accessToken = jwt.sign(
    { sub: payload.sub, email: payload.email, scope: payload.scope },
    process.env.ACCESS_SECRET,
    { expiresIn: '15m', issuer: 'https://api.example.com', audience: 'https://api.example.com' }
  );

  // Rotate refresh token
  const newRefreshToken = jwt.sign(
    { sub: payload.sub, email: payload.email, scope: payload.scope },
    process.env.REFRESH_SECRET,
    { expiresIn: '7d' }
  );
  refreshTokenStore.set(payload.sub, {
    token: newRefreshToken,
    issuedAt: Date.now(),
  });

  res.json({
    access_token: accessToken,
    refresh_token: newRefreshToken,
    token_type: 'Bearer',
    expires_in: 900,
  });
});

JWT Structure and Verification

JSON Web Tokens (JWT, RFC 7519) are the most common format for OAuth 2.0 access tokens and OIDC ID tokens. A JWT consists of three Base64URL-encoded parts separated by dots: Header.Payload.Signature.

The Header specifies the signing algorithm (alg) and token type (typ). Common algorithms are HS256 (HMAC-SHA256, symmetric — same key for signing and verification) and RS256 (RSA-SHA256, asymmetric — private key signs, public key verifies). For distributed systems, RS256 is preferred because resource servers can verify tokens using the public key without needing the private key.

The Payload contains claims — statements about the user and the token. Registered claims include iss (issuer), sub (subject/user ID), aud (audience), exp (expiration), iat (issued at), and jti (JWT ID for revocation). Public and private claims carry application-specific data like role, email, and scope. The payload is Base64URL encoded, not encrypted — never put sensitive data like passwords in a JWT payload.

The Signature is computed as: Base64URL(Header) + "." + Base64URL(Payload) signed with the algorithm and key specified in the header. Verifying the signature proves that the token was issued by a trusted party and has not been tampered with.

JWT Verification Checklist

• Verify the signature using the correct algorithm and key (fetch the JWKS endpoint to get current public keys)
• Check exp — reject tokens where exp < current time
• Check iss — the issuer must match your expected Authorization Server URL
• Check aud — the audience must include your API's identifier
• Check nbf — if present, the token must not be used before this time
• Check algorithm in header matches expected algorithm (prevent algorithm confusion attacks)

// JWT verification — Node.js with jose library (recommended)
import { createRemoteJWKSet, jwtVerify } from 'jose';

// Fetch public keys from Authorization Server's JWKS endpoint
const JWKS = createRemoteJWKSet(
  new URL('https://accounts.google.com/.well-known/jwks.json')
);

async function verifyAccessToken(token) {
  const { payload } = await jwtVerify(token, JWKS, {
    issuer: 'https://accounts.google.com',
    audience: 'https://api.yourapp.com',
    algorithms: ['RS256'],
  });

  // payload is verified — access claims safely
  return {
    userId: payload.sub,
    email: payload.email,
    scope: payload.scope,
    expiresAt: new Date(payload.exp * 1000),
  };
}

// Express.js middleware
async function requireAuth(req, res, next) {
  const header = req.headers.authorization;
  if (!header?.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'Bearer token required' });
  }
  try {
    const token = header.slice(7);
    req.user = await verifyAccessToken(token);
    next();
  } catch (err) {
    return res.status(401).json({ error: 'Invalid or expired token', details: err.message });
  }
}

// Python — JWT verification with PyJWT
"""
import jwt
from jwt import PyJWKClient

jwks_client = PyJWKClient("https://accounts.google.com/.well-known/jwks.json")

def verify_token(token: str) -> dict:
    signing_key = jwks_client.get_signing_key_from_jwt(token)
    payload = jwt.decode(
        token,
        signing_key.key,
        algorithms=["RS256"],
        audience="https://api.yourapp.com",
        issuer="https://accounts.google.com",
        options={"verify_exp": True}
    )
    return payload
"""

Implementation Examples: Node.js and Python

Node.js: Complete OAuth 2.0 Server with Passport.js

// Node.js / Express — OAuth 2.0 with Passport.js
// npm install passport passport-google-oauth20 express-session

const passport = require('passport');
const { Strategy: GoogleStrategy } = require('passport-google-oauth20');
const session = require('express-session');

app.use(session({
  secret: process.env.SESSION_SECRET,
  resave: false,
  saveUninitialized: false,
  cookie: { secure: true, httpOnly: true, sameSite: 'lax', maxAge: 24 * 3600 * 1000 },
}));
app.use(passport.initialize());
app.use(passport.session());

passport.use(new GoogleStrategy({
  clientID: process.env.GOOGLE_CLIENT_ID,
  clientSecret: process.env.GOOGLE_CLIENT_SECRET,
  callbackURL: 'https://yourapp.com/auth/google/callback',
  scope: ['openid', 'email', 'profile'],
}, async (accessToken, refreshToken, profile, done) => {
  // Find or create user in database
  let user = await db.users.findOne({ googleId: profile.id });
  if (!user) {
    user = await db.users.create({
      googleId: profile.id,
      email: profile.emails[0].value,
      name: profile.displayName,
      picture: profile.photos[0].value,
    });
  }
  // Store tokens if you need to call Google APIs on behalf of user
  await db.tokens.upsert({
    userId: user.id,
    accessToken,          // short-lived Google access token
    refreshToken,         // long-lived, only sent on first auth
  });
  return done(null, user);
}));

passport.serializeUser((user, done) => done(null, user.id));
passport.deserializeUser(async (id, done) => {
  const user = await db.users.findById(id);
  done(null, user);
});

// Routes
app.get('/auth/google', passport.authenticate('google'));
app.get('/auth/google/callback',
  passport.authenticate('google', { failureRedirect: '/login' }),
  (req, res) => res.redirect('/dashboard')
);
app.get('/auth/logout', (req, res) => {
  req.logout(() => res.redirect('/'));
});

// Protected route
app.get('/api/me', ensureAuthenticated, (req, res) => {
  res.json({ user: req.user });
});

function ensureAuthenticated(req, res, next) {
  if (req.isAuthenticated()) return next();
  res.status(401).json({ error: 'Not authenticated' });
}

Python: FastAPI + OAuth 2.0 (GitHub)

# Python FastAPI — GitHub OAuth 2.0
# pip install fastapi httpx python-dotenv

from fastapi import FastAPI, HTTPException, Request
from fastapi.responses import RedirectResponse
import httpx
import secrets
import os

app = FastAPI()
state_store = {}  # Use Redis in production

GITHUB_CLIENT_ID = os.getenv("GITHUB_CLIENT_ID")
GITHUB_CLIENT_SECRET = os.getenv("GITHUB_CLIENT_SECRET")
REDIRECT_URI = "https://yourapp.com/auth/github/callback"

@app.get("/auth/github")
async def github_login():
    state = secrets.token_urlsafe(32)
    state_store[state] = True
    params = {
        "client_id": GITHUB_CLIENT_ID,
        "redirect_uri": REDIRECT_URI,
        "scope": "read:user user:email",
        "state": state,
    }
    url = "https://github.com/login/oauth/authorize?" + "&".join(
        f"{k}={v}" for k, v in params.items()
    )
    return RedirectResponse(url)

@app.get("/auth/github/callback")
async def github_callback(code: str, state: str):
    # Validate state to prevent CSRF
    if state not in state_store:
        raise HTTPException(status_code=400, detail="Invalid state parameter")
    del state_store[state]

    async with httpx.AsyncClient() as client:
        # Exchange code for access token
        token_res = await client.post(
            "https://github.com/login/oauth/access_token",
            json={
                "client_id": GITHUB_CLIENT_ID,
                "client_secret": GITHUB_CLIENT_SECRET,
                "code": code,
                "redirect_uri": REDIRECT_URI,
            },
            headers={"Accept": "application/json"},
        )
        token_data = token_res.json()
        access_token = token_data["access_token"]

        # Fetch user profile
        user_res = await client.get(
            "https://api.github.com/user",
            headers={"Authorization": f"Bearer {access_token}", "Accept": "application/json"},
        )
        user = user_res.json()

    # Create session or JWT for your app
    return {"user_id": user["id"], "login": user["login"], "email": user["email"]}

OAuth 2.0 Security Best Practices

// Security checklist implementation

// 1. Validate redirect_uri strictly (server-side)
const ALLOWED_REDIRECT_URIS = [
  'https://yourapp.com/auth/callback',
  'https://staging.yourapp.com/auth/callback',
];

function validateRedirectUri(uri) {
  return ALLOWED_REDIRECT_URIS.includes(uri);
}

// 2. Validate state parameter
function generateState() {
  return Buffer.from(crypto.randomBytes(32)).toString('base64url');
}

function validateState(received, stored) {
  if (!received || !stored) return false;
  // Use constant-time comparison to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(received),
    Buffer.from(stored)
  );
}

// 3. Token introspection — verify opaque tokens
async function introspectToken(token) {
  const res = await fetch('https://auth.example.com/oauth/introspect', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': 'Basic ' + Buffer.from(
        process.env.CLIENT_ID + ':' + process.env.CLIENT_SECRET
      ).toString('base64'),
    },
    body: new URLSearchParams({ token }),
  });
  const data = await res.json();
  if (!data.active) throw new Error('Token is not active');
  return data;
}

// 4. Revoke tokens on logout
async function revokeToken(token, tokenTypeHint = 'access_token') {
  await fetch('https://auth.example.com/oauth/revoke', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      token,
      token_type_hint: tokenTypeHint,
      client_id: process.env.CLIENT_ID,
      client_secret: process.env.CLIENT_SECRET,
    }),
  });
}

Social Login: Google, GitHub, and Facebook OAuth

Social login (Sign in with Google/GitHub/Facebook) uses OAuth 2.0 under the hood. Each provider has slightly different scopes, endpoints, and token behaviors. Here is a comparison of the three most popular providers.

// Unified social login handler — Node.js
// Works with Google, GitHub, Facebook

const PROVIDERS = {
  google: {
    authUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
    tokenUrl: 'https://oauth2.googleapis.com/token',
    userUrl: 'https://openidconnect.googleapis.com/v1/userinfo',
    scope: 'openid email profile',
    clientId: process.env.GOOGLE_CLIENT_ID,
    clientSecret: process.env.GOOGLE_CLIENT_SECRET,
  },
  github: {
    authUrl: 'https://github.com/login/oauth/authorize',
    tokenUrl: 'https://github.com/login/oauth/access_token',
    userUrl: 'https://api.github.com/user',
    scope: 'read:user user:email',
    clientId: process.env.GITHUB_CLIENT_ID,
    clientSecret: process.env.GITHUB_CLIENT_SECRET,
  },
  facebook: {
    authUrl: 'https://www.facebook.com/v18.0/dialog/oauth',
    tokenUrl: 'https://graph.facebook.com/v18.0/oauth/access_token',
    userUrl: 'https://graph.facebook.com/me?fields=id,name,email,picture',
    scope: 'email,public_profile',
    clientId: process.env.FACEBOOK_APP_ID,
    clientSecret: process.env.FACEBOOK_APP_SECRET,
  },
};

app.get('/auth/:provider', (req, res) => {
  const provider = PROVIDERS[req.params.provider];
  if (!provider) return res.status(404).json({ error: 'Unknown provider' });

  const state = generateState();
  req.session.oauthState = state;
  req.session.oauthProvider = req.params.provider;

  const params = new URLSearchParams({
    response_type: 'code',
    client_id: provider.clientId,
    redirect_uri: 'https://yourapp.com/auth/callback',
    scope: provider.scope,
    state,
  });
  res.redirect(provider.authUrl + '?' + params);
});

app.get('/auth/callback', async (req, res) => {
  const { code, state } = req.query;
  const providerName = req.session.oauthProvider;
  const provider = PROVIDERS[providerName];

  if (!validateState(state, req.session.oauthState)) {
    return res.status(403).json({ error: 'Invalid state' });
  }

  // Exchange code for token
  const tokenRes = await fetch(provider.tokenUrl, {
    method: 'POST',
    headers: { 'Accept': 'application/json', 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      client_id: provider.clientId,
      client_secret: provider.clientSecret,
      code,
      redirect_uri: 'https://yourapp.com/auth/callback',
    }),
  });
  const { access_token } = await tokenRes.json();

  // Fetch user profile
  const userRes = await fetch(provider.userUrl, {
    headers: { Authorization: 'Bearer ' + access_token },
  });
  const profile = await userRes.json();

  // Upsert user in your database
  const user = await upsertUser(providerName, profile);
  req.session.userId = user.id;
  res.redirect('/dashboard');
});

OpenID Connect (OIDC) Explained

OpenID Connect is an identity layer built directly on top of OAuth 2.0. It adds a standardized way to authenticate users and retrieve their profile information. While OAuth 2.0 answers "Can this app access this resource?", OIDC answers "Who is this user?"

OIDC introduces three key additions to OAuth 2.0: the ID token (a JWT containing user identity claims), the UserInfo endpoint (for fetching additional claims beyond what fits in the ID token), and a standardized discovery document (.well-known/openid-configuration) that describes the provider's endpoints and capabilities.

Standard OIDC Claims

OIDC defines a set of standard claims in the ID token payload. The sub claim is the unique user identifier (do not use email as a user identifier — it can change). The name, given_name, and family_name claims provide the user's display name. The email and email_verified claims give the user's email and whether it has been verified. The picture claim is a URL to the user's profile photo.

OIDC Authorization Code Flow

// OpenID Connect — Complete Implementation
// Using the openid-client library (recommended)
// npm install openid-client

import { Issuer, generators } from 'openid-client';

// Discovery — fetches .well-known/openid-configuration automatically
const googleIssuer = await Issuer.discover('https://accounts.google.com');

const client = new googleIssuer.Client({
  client_id: process.env.GOOGLE_CLIENT_ID,
  client_secret: process.env.GOOGLE_CLIENT_SECRET,
  redirect_uris: ['https://yourapp.com/auth/callback'],
  response_types: ['code'],
});

// Generate auth URL with PKCE
app.get('/auth/login', (req, res) => {
  const codeVerifier = generators.codeVerifier();
  const codeChallenge = generators.codeChallenge(codeVerifier);
  const state = generators.state();
  const nonce = generators.nonce(); // OIDC-specific replay protection

  req.session.codeVerifier = codeVerifier;
  req.session.state = state;
  req.session.nonce = nonce;

  const url = client.authorizationUrl({
    scope: 'openid email profile',
    code_challenge: codeChallenge,
    code_challenge_method: 'S256',
    state,
    nonce,
  });
  res.redirect(url);
});

// Handle callback
app.get('/auth/callback', async (req, res) => {
  const params = client.callbackParams(req);

  // Exchange code for tokens — validates state, nonce, and token claims
  const tokenSet = await client.callback(
    'https://yourapp.com/auth/callback',
    params,
    {
      code_verifier: req.session.codeVerifier,
      state: req.session.state,
      nonce: req.session.nonce,
    }
  );

  // tokenSet.access_token — use to call APIs
  // tokenSet.id_token — contains user identity
  // tokenSet.claims() — parsed ID token payload

  const claims = tokenSet.claims();
  // claims.sub — unique user ID (stable, use as primary key)
  // claims.email — user email
  // claims.name — display name
  // claims.picture — avatar URL
  // claims.email_verified — boolean

  const user = await upsertUser({
    oidcSub: claims.sub,
    email: claims.email,
    name: claims.name,
    picture: claims.picture,
  });

  req.session.userId = user.id;
  res.redirect('/dashboard');
});

OAuth 2.0 vs SAML vs JWT: Which to Choose?

Three protocols dominate enterprise identity and API security. Understanding when to use each saves significant architectural pain.

Common OAuth Vulnerabilities and Prevention

// Scope validation middleware — Express.js
function requireScope(...requiredScopes) {
  return (req, res, next) => {
    const tokenScopes = (req.user.scope || '').split(' ');
    const hasAllScopes = requiredScopes.every(s => tokenScopes.includes(s));
    if (!hasAllScopes) {
      return res.status(403).json({
        error: 'insufficient_scope',
        required: requiredScopes,
        granted: tokenScopes,
      });
    }
    next();
  };
}

// Usage
app.get('/api/reports', requireAuth, requireScope('read:reports'), getReports);
app.post('/api/data', requireAuth, requireScope('write:data'), createData);
app.delete('/api/data/:id', requireAuth, requireScope('write:data', 'admin'), deleteData);

// Audience validation in token verification
async function verifyTokenStrict(token) {
  const { payload } = await jwtVerify(token, JWKS, {
    issuer: process.env.EXPECTED_ISSUER,
    audience: process.env.API_IDENTIFIER, // e.g. "https://api.yourapp.com"
    algorithms: ['RS256'],
    clockTolerance: 30, // 30 second clock skew allowance
  });
  return payload;
}

FAQ