Prerequisites

The Problem Being Solved

Suppose a reporting application needs to read a user's files from a storage platform. The naive approach is to ask the user for their storage password and log in on their behalf.

OAuth 2.0 is the framework that makes the second approach standard. It allows one application to act on a resource with limited permission, without ever seeing the user's credentials.

OAuth 2.0 Roles

OAuth 2.0 Is Not Authentication

This is the most consequential misunderstanding in the topic. OAuth 2.0 is an authorization framework. An access token states that a client may perform certain operations. It does not, by itself, reliably tell the client who the user is.

What OpenID Connect Adds

OpenID Connect, commonly written as OIDC, is an identity layer built on top of OAuth 2.0. It reuses the same flows and endpoints but adds a standardized way to prove and describe user identity.

The Three Token Types

Example ID Token Claims

{
    "iss": "https://identity.example.com",
    "sub": "user-4821",
    "aud": "reporting-web-client",
    "exp": 1790000000,
    "iat": 1789996400,
    "auth_time": 1789996390,
    "nonce": "n-3f9a2c7b",
    "email": "user@example.com",
    "email_verified": true,
    "name": "Example User"
}

The Authorization Code Flow

The authorization code flow is the recommended default for applications acting on behalf of a user. The browser never carries tokens in its address bar, because a short-lived code is exchanged for tokens over a direct back-channel request.

1. The client redirects the user to the authorization server.
2. The user authenticates and approves the requested scopes.
3. The server redirects back with a single-use authorization code.
4. The client verifies the returned state value.
5. The client exchanges the code at the token endpoint.
6. The server returns access, ID, and possibly refresh tokens.
7. The client validates the ID token before establishing a session.
8. The client calls APIs using the access token.

Authorization Request

GET /authorize
    ?response_type=code
    &client_id=reporting-web-client
    &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
    &scope=openid%20profile%20email%20reports.read
    &state=stt-7c1d9e4a
    &nonce=n-3f9a2c7b
    &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
    &code_challenge_method=S256 HTTP/1.1
Host: identity.example.com

Token Exchange

{
    "grant_type": "authorization_code",
    "code": "auth-code-9f2b71c4",
    "redirect_uri": "https://app.example.com/callback",
    "client_id": "reporting-web-client",
    "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
}

Token Response

{
    "access_token": "opaque-or-jwt-access-token",
    "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "refresh-token-value",
    "token_type": "Bearer",
    "expires_in": 900,
    "scope": "openid profile email reports.read"
}

PKCE: Proof Key for Code Exchange

PKCE protects the authorization code against interception. The client generates a random secret before starting the flow, sends only its hash in the authorization request, and reveals the original value during the token exchange.

An attacker who steals the authorization code cannot exchange it, because they do not possess the verifier that matches the challenge recorded at the authorization server.

function base64UrlEncode(buffer) {
    return btoa(String.fromCharCode(...new Uint8Array(buffer)))
        .replace(/\+/g, "-")
        .replace(/\//g, "_")
        .replace(/=+$/, "");
}

async function createPkcePair() {
    const randomBytes = new Uint8Array(32);
    crypto.getRandomValues(randomBytes);

    const codeVerifier = base64UrlEncode(randomBytes.buffer);

    const digest = await crypto.subtle.digest(
        "SHA-256",
        new TextEncoder().encode(codeVerifier)
    );

    return {
        codeVerifier: codeVerifier,
        codeChallenge: base64UrlEncode(digest),
        codeChallengeMethod: "S256"
    };
}

State and Nonce

These two parameters defend against different attacks and are frequently confused.

Choosing the Right Grant

Client Credentials for Service-to-Service

When no user is involved, the client authenticates as itself. A background indexing job calling an internal API is a typical example.

{
    "grant_type": "client_credentials",
    "client_id": "search-indexer",
    "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
    "client_assertion": "eyJhbGciOiJSUzI1NiJ9...",
    "scope": "catalog.read index.write"
}

Validating Tokens Correctly

Validation is where most implementation defects appear. Every check below exists because skipping it enables a specific attack.

async function validateIdToken(idToken, expected) {
    const { header, payload, signature } = decodeJwt(idToken);

    if (!expected.allowedAlgorithms.includes(header.alg)) {
        throw new Error("Unsupported signing algorithm");
    }

    const signingKey = await getSigningKey(
        expected.issuer,
        header.kid
    );

    const signatureValid = await verifySignature(
        idToken,
        signingKey,
        header.alg
    );

    if (!signatureValid) {
        throw new Error("Invalid token signature");
    }

    if (payload.iss !== expected.issuer) {
        throw new Error("Unexpected issuer");
    }

    const audiences = Array.isArray(payload.aud)
        ? payload.aud
        : [payload.aud];

    if (!audiences.includes(expected.clientId)) {
        throw new Error("Token audience mismatch");
    }

    const nowSeconds = Math.floor(Date.now() / 1000);

    if (payload.exp <= nowSeconds - expected.clockSkewSeconds) {
        throw new Error("Token expired");
    }

    if (payload.nonce !== expected.nonce) {
        throw new Error("Nonce mismatch");
    }

    return payload;
}

Opaque Tokens and Introspection

Not all access tokens are JWTs. An opaque token is a reference that carries no readable content, and the resource server asks the authorization server about its validity.

Refresh Tokens and Rotation

Refresh tokens let a client obtain new access tokens without interrupting the user. Because they are long-lived, they are a high-value target and require stronger handling.

CREATE TABLE refresh_tokens (
    token_id        VARCHAR(64) PRIMARY KEY,
    family_id       VARCHAR(64) NOT NULL,
    subject_id      VARCHAR(64) NOT NULL,
    client_id       VARCHAR(64) NOT NULL,
    token_hash      VARCHAR(128) NOT NULL,
    issued_at       TIMESTAMP NOT NULL,
    expires_at      TIMESTAMP NOT NULL,
    consumed_at     TIMESTAMP NULL,
    revoked_at      TIMESTAMP NULL
);

UPDATE refresh_tokens
SET revoked_at = CURRENT_TIMESTAMP
WHERE family_id = :family_id
  AND revoked_at IS NULL;

If a previously consumed refresh token is presented again, the authorization server should assume theft and revoke the entire token family, forcing a fresh authentication.

Scopes Versus Permissions

A scope describes what the client was authorized to request. It does not describe what the user is entitled to access. Both checks are required.

async function getReport(request, response) {
    const claims = request.tokenClaims;

    if (!claims.scope.split(" ").includes("reports.read")) {
        return response.status(403).json({
            error: "insufficient_scope"
        });
    }

    const report = await reportRepository.findById(
        request.params.reportId
    );

    if (!report) {
        return response.status(404).json({ error: "not_found" });
    }

    const permitted = await authorizationService.canView(
        claims.sub,
        report
    );

    if (!permitted) {
        return response.status(404).json({ error: "not_found" });
    }

    return response.json(report);
}

Threats and Mitigations

Where Browser Applications Should Store Tokens

The backend-for-frontend pattern places a server component between the browser and the APIs. The browser holds only a session cookie, while the server holds the tokens and attaches them to outbound API calls.

Logout and Session Termination

Clearing a local session is not a complete logout. Several layers may retain valid state.

Discovery Configuration

{
    "issuer": "https://identity.example.com",
    "authorization_endpoint": "https://identity.example.com/authorize",
    "token_endpoint": "https://identity.example.com/token",
    "userinfo_endpoint": "https://identity.example.com/userinfo",
    "jwks_uri": "https://identity.example.com/.well-known/jwks.json",
    "end_session_endpoint": "https://identity.example.com/logout",
    "response_types_supported": ["code"],
    "id_token_signing_alg_values_supported": ["RS256", "ES256"],
    "code_challenge_methods_supported": ["S256"]
}

Using discovery allows clients to adapt to endpoint and key changes without redeployment, provided the document is retrieved over a verified connection and cached sensibly.

Monitoring and Detection

Common Implementation Mistakes

System Design Interview Discussion

Implementation Checklist

Knowledge Check

Summary

OAuth 2.0 is a delegated authorization framework built around four roles and several grant types. It replaces credential sharing with limited, expiring, revocable tokens issued by an authorization server.

OpenID Connect layers authentication on top of OAuth 2.0, introducing the ID token with standardized claims, a UserInfo endpoint, and discovery metadata. Access tokens authorize API calls, ID tokens establish identity, and refresh tokens renew access.

The authorization code flow with PKCE is the recommended default for user-facing clients, while client credentials suits service-to-service communication. Implicit and password grants are discouraged in current guidance.

Correctness depends on disciplined validation: verify the signature, enforce the expected algorithm, check issuer, audience, expiry, and nonce, and then enforce resource-level authorization separately from scope.