OAuth 2.0 and OpenID Connect: A Deep Dive

Why this trips everyone up

The single biggest source of confusion is that OAuth 2.0 and OpenID Connect solve two different problems that happen to live in the same flow. OAuth2 answers *authorization*: 'is this app allowed to call this API on the user's behalf?' OpenID Connect (OIDC) answers *authentication*: 'who is this user, and can I prove it?' OIDC is a thin identity layer built on top of OAuth2, same redirects, same endpoints, one extra token.

If the authentication-versus-authorization distinction is fuzzy, read authentication vs authorization first, the rest of this article leans on it constantly.

A mental model: the hotel keycard

OAuth2 is the protocol for handing out limited, revocable keys to your stuff, without ever handing over your master password.

Think about checking into a hotel. You prove who you are once at the front desk (you authenticate). The desk does not give you the master key to the whole building. It encodes a keycard that opens only your room, only until checkout. You can hand that card to a friend to grab your bag, they get into the room without ever knowing your identity or your credit card. That is delegated, scoped, time-limited access. That is OAuth2.

The valet-key idea is the heart of it: a valet key starts the car and drives it but cannot open the glovebox or trunk. A good access token is the same, it grants exactly the permissions the app asked for and the user agreed to, and nothing more.

The four roles

Every OAuth2 flow is a conversation between exactly four parties. Naming them precisely is half the battle, because the specs use these exact words.

• Resource owner, the human who owns the data. Usually just 'the user'. They are the only one who can grant consent.
• Client, the application that wants access. A SPA, a mobile app, or a backend. The client is *never* trusted with the user's password.
• Authorization server, the identity provider (Google, Auth0, Okta, Keycloak, Microsoft Entra). It authenticates the user, shows the consent screen, and issues tokens.
• Resource server, the API holding the protected data. It accepts an access token, validates it, and serves (or refuses) the request.

The picture: Authorization Code flow with PKCE

The Authorization Code flow with PKCE (pronounced 'pixy', Proof Key for Code Exchange) is the modern default for every client type, SPAs, mobile, and traditional web apps alike. The key idea: the browser never receives tokens directly. It receives a short-lived authorization code, then a separate back-channel call swaps that code for tokens, proving it is the same client that started the flow.

1. 1

   Generate the PKCE pair

   The client invents a random secret, the code_verifier, hashes it (SHA-256) into a code_challenge, and stashes the verifier locally. The challenge is sent now; the verifier is revealed only at step 4.

2. 2

   Redirect to /authorize

   The browser is sent to the authorization server with client_id, redirect_uri, scope, a random state (anti-CSRF), and the code_challenge. The user logs in and approves the consent screen here, on the auth server's domain, never the client's.

3. 3

   Receive the authorization code

   The auth server redirects back to the registered redirect_uri with a short-lived ?code=... and the same state. The client verifies state matches what it sent. The code alone is useless to an attacker.

4. 4

   Exchange the code for tokens

   The client POSTs the code plus the original code_verifier to the /token endpoint. The server re-hashes the verifier and checks it equals the earlier challenge. Match means it is the same client, so it returns the access, ID, and refresh tokens.

5. 5

   Call the API

   The client sends the access token as an Authorization: Bearer header on every API request. The resource server validates it and serves the data.

Why does PKCE matter? Without it, an attacker who intercepts the authorization code (a malicious app registered for the same redirect URI on mobile, or a leaky redirect) could redeem it for tokens. With PKCE, the code is worthless without the matching code_verifier, which never left the legitimate client. That is why PKCE is now mandatory even for confidential web apps in OAuth 2.1.

Three tokens, three jobs

A successful flow can hand back three tokens, and mixing them up is the second-biggest source of bugs. They are not interchangeable.

Grant types: which to use, which are dead

OAuth2 historically offered several 'grant types' (ways to obtain tokens). Most are now actively discouraged. The short version: use Authorization Code + PKCE for anything with a user, and Client Credentials for machine-to-machine. Avoid the rest.

Why implicit is dead: it returned the access token directly in the redirect URL fragment, where it landed in browser history, server logs, and referrer headers, and it had no way to deliver a refresh token safely. PKCE made it obsolete. Why password grant is dead: it requires the user to type their password *into the client app*, which is exactly the trust violation OAuth was invented to avoid. If the app sees the password, there is no point delegating.

Inside a JWT

ID tokens (and often access tokens) are JWTs, JSON Web Tokens. A JWT is three Base64URL-encoded parts joined by dots: header.payload.signature. It is *encoded, not encrypted*, anyone can read the contents. The signature is what makes it trustworthy: it proves the token was issued by the auth server and has not been tampered with.

// Part 1 - HEADER (which algorithm + which key signed this)
{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "a1b2c3d4"        // key id, used to find the right public key
}

// Part 2 - PAYLOAD (the claims)
{
  "iss": "https://auth.example.com",  // issuer
  "aud": "my-client-id",              // audience (who this is for)
  "sub": "user_8f3k2",                // subject (the user id)
  "exp": 1717689600,                    // expiry (unix seconds)
  "iat": 1717686000,                    // issued at
  "email": "ada@example.com",
  "scope": "openid profile read:invoices"
}

// Part 3 - SIGNATURE (not JSON; a cryptographic signature over parts 1+2)
//   RSASHA256( base64url(header) + "." + base64url(payload), privateKey )

Validation is non-negotiable, and 'it decodes fine' is not validation. You must verify, in order: the signature (using the auth server's public key, looked up by kid from its JWKS endpoint), the issuer (iss), the audience (aud), and the expiry (exp). Skip any one and you have a hole.

import { createRemoteJWKSet, jwtVerify } from 'jose';

// 1. Point at the auth server's published public keys (cached & rotated for you)
const JWKS = createRemoteJWKSet(
  new URL('https://auth.example.com/.well-known/jwks.json'),
);

export async function verifyAccessToken(token: string) {
  // 2. jwtVerify checks the signature against JWKS, AND iss/aud/exp in one call
  const { payload } = await jwtVerify(token, JWKS, {
    issuer: 'https://auth.example.com',  // must match iss
    audience: 'my-api',                  // must match aud (the API, not the client)
  });

  // 3. exp is enforced automatically; reaching here means the token is valid.
  return payload; // { sub, scope, ... } - now safe to authorize against
}

Scopes and consent

Scopes are the valet-key restrictions. When the client redirects to /authorize, it lists the scopes it wants, openid profile read:invoices. The authorization server shows the user a consent screen spelling out exactly what the app is asking for, and the user approves or denies. The issued token carries only the granted scopes; the resource server then checks the scope before serving each endpoint.

• `openid` is the magic scope: requesting it is what turns a plain OAuth2 request into an OIDC one and makes the auth server return an ID token.
• `profile` / `email` are standard OIDC scopes for basic identity claims.
• `read:invoices`, `write:orders` are your own API scopes, design them around resources and actions, not around roles.
• Least privilege: ask only for what the feature needs right now. A photo-printing app asking for full Drive access is the consent-screen equivalent of a red flag.

Token storage in SPAs: the BFF pattern

Now the part that breaks real apps. Where does a single-page app keep its tokens? Every option in the browser has a sharp edge.

The modern answer is the Backend-For-Frontend (BFF) pattern. Instead of letting the browser hold tokens at all, you run a thin server beside your SPA. The BFF performs the Authorization Code + PKCE flow, holds the tokens server-side, and gives the browser only an httpOnly, Secure, SameSite session cookie. The browser can never read that cookie from JavaScript, so XSS cannot exfiltrate tokens. The BFF attaches the real access token to API calls on the user's behalf.

If a BFF is genuinely out of reach, the least-bad fallback is keeping the access token in memory only (a JavaScript variable, lost on refresh) and using a refresh token in an httpOnly cookie with rotation. But for anything handling real user data, the BFF is the recommended pattern in 2026.

Common mistakes that cost hours

1. Skipping `state` validation. Without the anti-CSRF state check on the callback, an attacker can fixate a login. Always generate it, store it, and compare it.
2. Decoding a JWT and calling it 'verified'. Decoding reads the claims; it proves nothing. Always verify signature + iss + aud + exp.
3. Sending the ID token to your API. The API must accept access tokens only. Check the aud claim and reject mismatches.
4. Storing tokens in localStorage. Use httpOnly cookies via a BFF, or in-memory at minimum.
5. Trusting the token's own `alg` header. Pin the algorithm server-side and reject none.
6. Long-lived access tokens 'to avoid re-login'. Keep access tokens short; use refresh tokens for longevity so you can actually revoke a session.
7. Treating scopes as roles. Scopes describe what the token may do; do your role/permission checks server-side against the user, not by trusting a scope as authority.

Takeaways

Where to go next

OAuth2 and OIDC sit in the middle of a larger security picture. To go deeper, follow these threads:

• authentication vs authorization, the foundation this whole article rests on.
• passkeys and WebAuthn, how users prove identity to the auth server in the first place, without passwords.
• HTTPS, TLS, and encryption basics, why tokens in transit are safe (and why they never should travel over plain HTTP).
• the OWASP API Security Top 10, broken authorization and token mishandling are top entries; this is the checklist for hardening the resource server.

Once these click, you will read any 'Sign in with...' integration guide and recognize every step, because you will know which role, which token, and which flow it is talking about.