🔐 OAuth 2.0 Flow Explained

What Problem Does OAuth Solve?

Imagine a photo-printing site wants to grab the photos from your Google account. The naive approach would be to ask for your Google email and password and log in as you. That's a disaster: the site now knows your password, can read your email, can change your account, and there's no way to revoke just the printing site without changing your password everywhere.

OAuth 2.0 is the industry-standard protocol that fixes this. It lets you grant an app limited, revocable access to specific parts of your account — without ever handing over your credentials.

When you click "Sign in with Google," three things are true that make OAuth worth the complexity:

• You never type your Google password into the third-party site — you type it into Google's page.
• You grant a specific scope (say, "read your profile and email") — not blanket access.
• You can visit your Google account settings later and revoke that one app, leaving everything else intact.

The Four Roles

OAuth defines four roles. Everything in the protocol is a message passing between them. Learn these names — the whole spec reads clearly once you do.

A few more terms you'll meet constantly:

Authorization vs. Authentication

This is the single most important conceptual point in the lesson, and it trips up experienced developers.

• Authentication answers "who are you?" — proving identity.
• Authorization answers "what are you allowed to do?" — granting access.

Plain OAuth 2.0 is a delegated authorization protocol. Its job is to give a client a token that grants access to resources. It was not originally designed to tell the client "who the user is."

The Authorization Code Flow

The Authorization Code flow is the workhorse of OAuth. It's the flow you'll use for any app with a server backend, and (with PKCE) for SPAs and mobile apps too. The key insight: sensitive token exchange happens server-to-server, out of reach of the browser.

Here is the complete choreography. Read the diagram top to bottom — this is the sequence you'll implement.

Step 1 — Send the user to the authorization server

The client builds a URL to the provider's /authorize endpoint and redirects the browser there. Notice it generates a random state and stores it in the session first.

const crypto = require('crypto');

// Step 1: Redirect the user to the provider's consent screen
app.get('/auth/login', (req, res) => {
  // A random, unguessable value tied to THIS browser session (CSRF defense)
  const state = crypto.randomBytes(16).toString('hex');
  req.session.oauthState = state;

  const authUrl = new URL('https://authorization-server.com/oauth/authorize');
  authUrl.searchParams.set('response_type', 'code');          // ask for an auth CODE
  authUrl.searchParams.set('client_id', process.env.OAUTH_CLIENT_ID);
  authUrl.searchParams.set('redirect_uri', process.env.OAUTH_REDIRECT_URI);
  authUrl.searchParams.set('scope', 'profile email');         // least privilege
  authUrl.searchParams.set('state', state);

  res.redirect(authUrl.toString());
});

Why it matters: the browser is only ever redirected to the provider. Your server never sees the user's provider password — that's the whole point.

Step 2 — User authenticates and consents

On the provider's own domain, the user logs in (if not already) and sees a consent screen: "This app wants to view your profile and email. Allow?" The provider — not you — handles passwords, 2FA, and CAPTCHAs.

Step 3 — The provider redirects back with a code

On approval, the provider redirects the browser to your registered redirect_uri with two query parameters: a short-lived code (usually valid ~10 minutes, single use) and the original state.

Step 4 — Exchange the code for tokens (server-side!)

Your server verifies state, then makes a back-channel POST to the token endpoint, including the client_secret. This request never touches the browser.

// Step 3 & 4: Handle the callback and swap the code for tokens
app.get('/auth/callback', async (req, res) => {
  const { code, state } = req.query;

  // Verify state matches what we stored — blocks CSRF (see next section)
  if (!state || state !== req.session.oauthState) {
    return res.status(403).send('Invalid state parameter');
  }
  delete req.session.oauthState; // one-time use

  try {
    // Back-channel, server-to-server token exchange
    const tokenRes = await fetch('https://authorization-server.com/oauth/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        grant_type: 'authorization_code',
        code,
        redirect_uri: process.env.OAUTH_REDIRECT_URI,     // must match step 1 exactly
        client_id: process.env.OAUTH_CLIENT_ID,
        client_secret: process.env.OAUTH_CLIENT_SECRET    // SECRET — server only!
      })
    });
    const { access_token, refresh_token, expires_in } = await tokenRes.json();

    // Step 5: use the access token to read the user's profile
    const infoRes = await fetch('https://api.example.com/userinfo', {
      headers: { Authorization: `Bearer ${access_token}` }
    });
    const profile = await infoRes.json();

    // Create or update the user, then start a session
    const user = await findOrCreateUser(profile);
    req.session.userId = user.id;
    res.redirect('/dashboard');
  } catch (err) {
    console.error('OAuth error:', err);
    res.status(500).send('Authentication failed');
  }
});

The state Parameter & CSRF

The state parameter is a random value your app generates, stores in the session, and sends to the authorization server. The server echoes it back on the redirect. Your callback then checks that the returned state equals the stored one.

Without it, you're open to a login CSRF attack: an attacker completes step 1 with their own account, captures the resulting code, and tricks a victim's browser into hitting your callback with that code — silently logging the victim into the attacker's account. Because the attacker never generated the victim's session state, the mismatch check rejects the forged callback.

PKCE for Public Clients

The Authorization Code flow relies on the client_secret to prove the token request is genuine. But a public client — a single-page app or a mobile app — runs entirely on the user's device. Anything you ship there can be extracted, so it cannot keep a secret. That's where PKCE comes in.

PKCE ("Proof Key for Code Exchange," pronounced "pixie") replaces the static secret with a fresh, per-request secret the client makes up on the spot:

1. The client generates a random code verifier and keeps it locally.
2. It hashes the verifier (SHA-256) to produce a code challenge, which it sends in the authorization request.
3. At token-exchange time it sends the original verifier. The server hashes it and checks it matches the challenge it saw earlier.

An attacker who steals the authorization code from the redirect still can't redeem it — they never had the verifier, and they can't reverse the hash.

// Generate a PKCE code verifier and challenge in the browser (Web Crypto API)
function base64UrlEncode(bytes) {
  return btoa(String.fromCharCode(...new Uint8Array(bytes)))
    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
}

function generateCodeVerifier() {
  const bytes = new Uint8Array(32);          // 256 bits of entropy
  crypto.getRandomValues(bytes);
  return base64UrlEncode(bytes);
}

async function generateCodeChallenge(verifier) {
  const data = new TextEncoder().encode(verifier);
  const digest = await crypto.subtle.digest('SHA-256', data);
  return base64UrlEncode(digest);           // send this in the authorize request
}

async function startLogin() {
  const verifier = generateCodeVerifier();
  sessionStorage.setItem('pkce_verifier', verifier); // keep locally for the swap
  const challenge = await generateCodeChallenge(verifier);

  const url = new URL('https://authorization-server.com/oauth/authorize');
  url.searchParams.set('response_type', 'code');
  url.searchParams.set('client_id', 'YOUR_CLIENT_ID');   // no secret needed
  url.searchParams.set('redirect_uri', location.origin + '/callback');
  url.searchParams.set('scope', 'profile email');
  url.searchParams.set('state', generateCodeVerifier()); // reuse the random helper
  url.searchParams.set('code_challenge', challenge);
  url.searchParams.set('code_challenge_method', 'S256'); // always S256, never "plain"
  location.href = url.toString();
}

Choosing a Grant Type

OAuth defines several grant types (flows) for different situations. In modern applications your choice is simpler than the full list suggests.

Practice & Quiz

function buildAuthUrl(config, state) {
    // config = { authorizeEndpoint, clientId, redirectUri }
    // TODO: return the full authorization URL string
}
// Expected: contains response_type=code, the client_id, redirect_uri,
//           scope=profile+email, and the state value.

function buildAuthUrl(config, state) {
    const url = new URL(config.authorizeEndpoint);
    url.searchParams.set('response_type', 'code');
    url.searchParams.set('client_id', config.clientId);
    url.searchParams.set('redirect_uri', config.redirectUri);
    url.searchParams.set('scope', 'profile email');
    url.searchParams.set('state', state);
    return url.toString();
}

function verifyState(returnedState, session) {
    // Both must exist AND be equal. A missing stored state means
    // this browser never started the flow — reject it.
    return Boolean(
        session.oauthState &&
        returnedState &&
        returnedState === session.oauthState
    );
}

Best Practices & Pitfalls

✅ Do

• Use the Authorization Code flow, and add PKCE everywhere
• Generate a random, single-use state and verify it on the callback
• Exchange the code for tokens server-side, keeping the client_secret off the browser
• Register exact redirect_uri values and validate them — never allow open redirects
• Request the minimum scope your app actually needs
• Serve everything over HTTPS; store refresh tokens encrypted at rest

❌ Don't

• Never put the client_secret in front-end code, a mobile bundle, or a public repo
• Don't use the deprecated Implicit flow or the Resource Owner Password grant
• Don't skip state verification — it's your CSRF defense
• Don't put tokens in URLs or logs; send access tokens only in the Authorization header
• Don't treat a plain OAuth access token as proof of identity — use an OIDC id_token for that

Summary

📚 Additional Resources

• oauth.net — OAuth 2.0 overview and specs
• oauth.net — Proof Key for Code Exchange (PKCE)
• MDN — The URL API
• RFC 6749 — The OAuth 2.0 Authorization Framework

🚀 What's Next?

You now understand the protocol. Next you'll meet the library that makes it painless in Node.js: Passport.js Strategies — the pluggable middleware that wires Google, GitHub, and dozens of other providers into an Express app.