OAuth 2.0 Complete Guide 2026: Authorization Code, PKCE & Client Credentials Explained

import crypto from 'crypto';

// ── Step 1: Generate PKCE values ───────────────────────────────────────────
function generatePKCE() {
  const codeVerifier  = crypto.randomBytes(32).toString('base64url');
  const codeChallenge = crypto
    .createHash('sha256')
    .update(codeVerifier)
    .digest('base64url');
  return { codeVerifier, codeChallenge };
}

// ── Step 2: Build authorization URL ───────────────────────────────────────
function buildAuthUrl(codeChallenge, state) {
  const params = new URLSearchParams({
    response_type:          'code',
    client_id:              process.env.OAUTH_CLIENT_ID,
    redirect_uri:           'https://myapp.com/auth/callback',
    scope:                  'openid profile email',
    state,                  // CSRF protection — verify on callback
    code_challenge:         codeChallenge,
    code_challenge_method:  'S256',
  });
  return 'https://accounts.google.com/o/oauth2/auth?' + params.toString();
}

// ── Login handler — redirects user to authorization server ─────────────────
app.get('/auth/login', (req, res) => {
  const { codeVerifier, codeChallenge } = generatePKCE();
  const state = crypto.randomBytes(16).toString('hex');

  // Store both in session — needed on callback
  req.session.codeVerifier = codeVerifier;
  req.session.oauthState   = state;

  res.redirect(buildAuthUrl(codeChallenge, state));
});

// ── Callback handler — exchanges auth code for tokens ─────────────────────
app.get('/auth/callback', async (req, res) => {
  const { code, state, error } = req.query;

  if (error) return res.status(400).json({ error });

  // Verify CSRF state
  if (state !== req.session.oauthState) {
    return res.status(400).json({ error: 'State mismatch — possible CSRF attack' });
  }

  // Exchange authorization code for tokens
  const tokenRes = 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:     process.env.OAUTH_CLIENT_ID,
      client_secret: process.env.OAUTH_CLIENT_SECRET,
      redirect_uri:  'https://myapp.com/auth/callback',
      code,
      code_verifier: req.session.codeVerifier, // must match the challenge from step 1
    }).toString(),
  });

  if (!tokenRes.ok) {
    const err = await tokenRes.json();
    return res.status(400).json({ error: 'Token exchange failed', details: err });
  }

  const tokens = await tokenRes.json();
  // tokens: { access_token, refresh_token, id_token, expires_in, scope }

  // Store refresh token securely (HttpOnly cookie or encrypted DB column)
  req.session.refreshToken = tokens.refresh_token;
  req.session.accessToken  = tokens.access_token;

  // Fetch user profile with access token
  const profile = await fetch('https://openidconnect.googleapis.com/v1/userinfo', {
    headers: { Authorization: 'Bearer ' + tokens.access_token },
  }).then(r => r.json());

  // profile: { sub, email, name, picture, email_verified }
  await upsertUser({ googleId: profile.sub, email: profile.email, name: profile.name });

  res.redirect('/dashboard');
});

// ── Get a service access token ─────────────────────────────────────────────
// Cache this token in memory — reuse until expiry, then fetch a new one
let cachedToken = null;
let tokenExpiry  = 0;

async function getServiceToken() {
  if (cachedToken && Date.now() < tokenExpiry - 60_000) {
    return cachedToken; // return cached token with 60s buffer
  }

  const res = await fetch('https://auth.myplatform.com/oauth/token', {
    method:  'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body:    new URLSearchParams({
      grant_type:    'client_credentials',
      client_id:     process.env.SERVICE_CLIENT_ID,
      client_secret: process.env.SERVICE_CLIENT_SECRET,
      scope:         'read:orders write:fulfillment', // only what this service needs
    }).toString(),
  });

  if (!res.ok) throw new Error('Failed to get service token: ' + res.status);

  const data = await res.json();
  // { access_token, token_type: "Bearer", expires_in: 3600, scope }

  cachedToken = data.access_token;
  tokenExpiry  = Date.now() + data.expires_in * 1000;

  return cachedToken;
}

// ── Use the token to call a protected internal API ─────────────────────────
async function fetchOrder(orderId) {
  const token = await getServiceToken();

  const res = await fetch('https://orders-api.internal/orders/' + orderId, {
    headers: {
      Authorization:  'Bearer ' + token,
      'Content-Type': 'application/json',
    },
  });

  if (!res.ok) throw new Error('Order API error: ' + res.status);
  return res.json();
}

// No refresh_token with client credentials — just request a new access token when it expires

// ── Refresh access token silently ──────────────────────────────────────────
async function refreshAccessToken(refreshToken) {
  const res = await fetch('https://oauth2.googleapis.com/token', {
    method:  'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body:    new URLSearchParams({
      grant_type:    'refresh_token',
      client_id:     process.env.OAUTH_CLIENT_ID,
      client_secret: process.env.OAUTH_CLIENT_SECRET,
      refresh_token: refreshToken,
    }).toString(),
  });

  if (!res.ok) {
    // Refresh token expired or revoked — user must re-authenticate
    throw new Error('REFRESH_FAILED');
  }

  const data = await res.json();
  // { access_token, expires_in, scope, token_type }
  // Note: Google does NOT return a new refresh_token here — keep the original
  // Some providers DO rotate refresh tokens — always check the response

  return { accessToken: data.access_token, expiresIn: data.expires_in };
}

// ── Wrapper that auto-refreshes on 401 ────────────────────────────────────
async function oauthFetch(url, options, session) {
  let res = await fetch(url, {
    ...options,
    headers: { ...options.headers, Authorization: 'Bearer ' + session.accessToken },
  });

  if (res.status === 401) {
    try {
      const { accessToken } = await refreshAccessToken(session.refreshToken);
      session.accessToken = accessToken;
      // Retry with new token
      res = await fetch(url, {
        ...options,
        headers: { ...options.headers, Authorization: 'Bearer ' + session.accessToken },
      });
    } catch {
      // Refresh failed — session expired, redirect to login
      throw new Error('SESSION_EXPIRED');
    }
  }

  return res;
}