OAuth 2.0 and OpenID Connect: Delegated Authorization and Identity Done Right

TL;DR: OAuth 2.0 (RFC 6749, 2012) lets a user grant an application scoped access to their resources without sharing a password. ¹ OpenID Connect adds an identity layer so the app also knows who the user is. Authorization Code + PKCE is the only flow you should use for new code: SPAs, mobile, and server-side apps alike. OAuth 2.1 formalizes this by dropping Implicit and ROPC grants entirely and mandating PKCE for all clients. ² The spec’s flexibility was its greatest weakness (its lead editor resigned calling it “the biggest professional disappointment of my career” ³), but a decade of security BCPs has tightened it into a reliable protocol when implemented correctly.

Learning Objectives

After this module, you will be able to:

• Distinguish OAuth 2.0 (authorization) from OpenID Connect (authentication)
• Pick the right grant type: Auth Code + PKCE, Client Credentials, or Device Code
• Explain the roles of access tokens, refresh tokens, and ID tokens
• Design a secure token lifecycle with rotation, revocation, and sender-constraining
• Recognize common OAuth misconfigurations (open redirect, missing state, token leakage)
• Implement OIDC federation for CI/CD without long-lived secrets

Intuition

You are renting a car. The rental company does not need the keys to your house. They need proof that you can drive (your license) and a scoped authorization (the rental agreement) that lets you use this specific car for these specific dates. You never hand over your house keys, your bank PIN, or your passport. The rental agreement is revocable: if you crash the car, the company cancels it immediately.

Before OAuth, the web worked like handing over your house keys. Want a third-party app to read your Gmail contacts? Give it your Google password. The app could read your email, delete your Drive files, change your password. There was no scoping, no revocation, no audit trail. In late 2006, while Blaine Cook was working on Twitter’s OpenID implementation, he ran into a gap: OpenID could sign users in, but there was no open standard for delegating scoped API access without handing over a password. He, Chris Messina, David Recordon, Larry Halff, and others started sketching what became OAuth to fill that gap. The OAuth Core 1.0 final draft shipped in October 2007. ⁴

OAuth is the rental agreement for the web. The user (resource owner) visits the authorization server (the rental desk), approves a specific set of permissions (scopes), and the app receives a time-limited token (the rental agreement). The app never sees the password. The token can be revoked. The damage from theft is bounded.

This chapter builds on Authentication vs Authorization, which covered how to verify identity and enforce permissions. Here we focus on the protocol that delegates authorization across trust boundaries.

Theory

The password anti-pattern and OAuth’s origin

Before OAuth, delegated access meant sharing credentials. This was called the “password anti-pattern”: the user gives their username and password to a third-party app, which logs in on their behalf. The app has full access. The user cannot revoke it without changing their password (which breaks every other app). There is no audit trail of what the app did.

OAuth 1.0 (2007) introduced signed request tokens to solve this. It worked but required complex cryptographic signatures on every request. OAuth 2.0 (RFC 6749, October 2012) replaced signatures with bearer tokens over TLS, making implementation simpler but shifting security responsibility to the transport layer. ¹

The spec was deliberately a “framework” rather than a tight protocol. Eran Hammer, its lead editor, resigned in July 2012, removing his name from the spec and calling it “a bad protocol” that “can be turned into a good one” only through significant implementer skill. ³ He was right: the flexibility led to a decade of exploits. But the IETF responded with RFC 9700 (OAuth 2.0 Security Best Current Practice, January 2025) ⁵ and the in-progress OAuth 2.1 draft, which folds PKCE, native-app rules, and browser-based app rules into one document and removes the flows that kept failing. ²

OAuth 2.0 roles and grant types

Four roles interact in every OAuth flow:

flowchart LR
    RO[Resource Owner<br/>the user] -->|authorizes| C[Client<br/>the app]
    C -->|requests token| AS[Authorization Server<br/>issues tokens]
    AS -->|validates user| RO
    C -->|presents token| RS[Resource Server<br/>protects the API]
    AS -.->|trusts| RS

Resource Owner: the user who owns the data. Client: the application requesting access. Authorization Server (AS): authenticates the user, collects consent, issues tokens. Resource Server (RS): the API that validates tokens and serves protected data.

The grant types (flows) determine how the client obtains tokens:

The Implicit grant returned tokens directly in the URL fragment, leaking them via browser history, Referer headers, and JavaScript. ROPC gave the client the user’s password, defeating the entire purpose of OAuth. Both are dead. Do not use them. ⁵

Authorization Code + PKCE

This is the flow you will implement. PKCE (RFC 7636, pronounced “pixy”) adds a cryptographic binding between the authorization request and the token exchange, preventing code interception attacks. ⁶

The mechanism: before starting the flow, the client generates a random code_verifier (43 to 128 URL-safe characters; RFC 7636 Section 7.1 recommends at least 256 bits of entropy, typically produced by base64url-encoding 32 random octets). It computes code_challenge = BASE64URL(SHA256(code_verifier)) and sends the challenge in the authorization request. When exchanging the code for tokens, the client sends the raw verifier. The AS recomputes the hash and rejects if it does not match. An attacker who intercepts the authorization code cannot redeem it without the verifier. ⁶

sequenceDiagram
    participant U as User Agent
    participant C as Client
    participant AS as Authorization Server
    participant RS as Resource Server

    C->>C: generate code_verifier + code_challenge = S256(verifier)
    U->>AS: GET /authorize?response_type=code&code_challenge=...&state=...
    AS->>U: login + consent screen
    U->>AS: approve
    AS->>U: 302 redirect_uri?code=abc&state=xyz
    U->>C: deliver code + state
    C->>C: verify state matches session
    C->>AS: POST /token (code + code_verifier + client auth)
    AS->>AS: verify SHA256(code_verifier) == stored challenge
    AS->>C: access_token + id_token + refresh_token
    C->>RS: GET /resource (Authorization: Bearer token)
    RS->>C: protected data

Key security parameters in this flow:

• state: a one-time, cryptographically random value bound to the user’s session. Prevents CSRF. The AS returns it unchanged; the client rejects mismatches. ⁵
• nonce (OIDC): embedded in the ID token, prevents replay. The client checks the ID token’s nonce claim matches what it sent.
• redirect_uri: must be registered exactly (no wildcards, no substring matching). RFC 9700 mandates exact string comparison. ⁵

OAuth 2.1 makes PKCE mandatory for all clients, including confidential ones, because PKCE also prevents authorization code injection attacks where an attacker forces a victim to use the attacker’s code. ²

OpenID Connect

OAuth answers “what can this app do?” but not “who is this user?” Using an access token for login is a well-known anti-pattern: access tokens have aud = resource_server, not aud = client. A token minted for one client can be replayed to another if both share a resource server.

OpenID Connect (OIDC, 2014) fixes this by adding:

• ID token: a signed JWT with aud = client_id, containing identity claims (sub, iss, email, name). The client validates the signature against the AS’s JWKS, checks iss, aud, exp, and nonce.
• openid scope: triggers ID token issuance.
• Discovery document: /.well-known/openid-configuration publishes all endpoints, supported algorithms, and capabilities. Clients fetch this once at startup.
• UserInfo endpoint: returns additional profile claims for the authenticated user.
• JWKS endpoint: publishes the AS’s public keys for signature verification.

The critical rule: access tokens are for APIs. ID tokens are for login. Never use an access token to determine who the user is. Never send an ID token to a resource server.

JWT Deep Dive covers the token format, signing algorithms, and alg: none attacks in detail.

Token lifecycle and security

Access tokens are short-lived (5 to 60 minutes). They are typically Bearer tokens (RFC 6750): possession alone authorizes the call. This means a stolen access token grants full access until expiry.

Refresh tokens are long-lived credentials exchanged at the token endpoint for new access tokens without user interaction. RFC 9700 requires that refresh tokens for public clients use either sender-constraining (mTLS or DPoP) or rotation with reuse detection. ⁵

stateDiagram-v2
    [*] --> RT1: initial grant issues RT1
    RT1 --> RT2: client exchanges RT1 for new tokens, RT1 invalidated
    RT2 --> RT3: client exchanges RT2, RT2 invalidated
    RT3 --> Revoked: attacker replays RT1 (reuse detected, entire family revoked)
    RT3 --> RT4: legitimate exchange continues
    RT4 --> [*]

DPoP (RFC 9449, September 2023) binds tokens to a client-held key pair. Every API call includes a DPoP proof JWT signed by the client’s private key. The access token carries a cnf.jkt confirmation claim (the key’s thumbprint). A stolen access token is useless without the private key. This moves beyond Bearer semantics toward sender-constrained tokens.

Revocation (RFC 7009) and introspection (RFC 7662) round out the lifecycle. Revocation lets clients or admins invalidate tokens immediately. Introspection lets resource servers check token validity in real time (useful for opaque tokens that cannot be validated locally).

SPA token storage and the BFF pattern

Where should a single-page application store tokens? The answer matters because XSS is the dominant web vulnerability, and any script running in the page’s origin can read localStorage.

localStorage is not safe for tokens. Any successful XSS exfiltrates the access token, refresh token, and ID token. The attacker has full API access for the token’s lifetime. The IETF “OAuth 2.0 for Browser-Based Apps” BCP and Auth0’s documentation both recommend against it.

The Backend-for-Frontend (BFF) pattern is the recommended approach: a thin server owned by the same team as the SPA completes the OAuth flow, holds tokens server-side in an encrypted session, and exposes HttpOnly; Secure; SameSite=Lax session cookies to the browser. The SPA calls its own BFF; the BFF calls the upstream API with the real access token. Tokens never reach JavaScript.

Real-World Example

GitHub Actions OIDC federation to AWS eliminates long-lived cloud credentials from CI/CD pipelines. Since 2021, every GitHub Actions workflow run can mint a short-lived OIDC token signed by GitHub’s identity provider (https://token.actions.githubusercontent.com). AWS STS validates this token and returns temporary credentials, typically valid for 1 hour.

The flow works as follows:

sequenceDiagram
    participant WF as GitHub Actions Workflow
    participant GH as GitHub OIDC Issuer
    participant STS as AWS STS
    participant S3 as AWS Resource (S3, ECR, etc.)

    WF->>GH: request OIDC token (aud=sts.amazonaws.com)
    GH->>WF: signed JWT (sub=repo:octo/app:ref:refs/heads/main)
    WF->>STS: AssumeRoleWithWebIdentity(RoleArn, JWT)
    STS->>GH: fetch JWKS, validate signature
    STS->>STS: check trust policy (aud, sub match)
    STS->>WF: temporary credentials (1h default)
    WF->>S3: API call with temp creds

The JWT’s sub claim encodes the caller’s identity: repo:octo/app:ref:refs/heads/main. The AWS IAM role’s trust policy matches against this, so a workflow in a different repository cannot assume the role.

The critical misconfiguration: Datadog Security Labs documented real-world trust-policy mistakes in July 2023 where organizations used StringLike on sub without anchoring to a specific repo, or omitted the aud check entirely. ⁷ Any repository on github.com could assume the victim’s role. The fix: always pin both aud to sts.amazonaws.com and sub to the exact repo:org/name:ref:refs/heads/branch pattern.

This pattern extends beyond GitHub. GitLab CI, CircleCI, and Bitbucket Pipelines all offer similar OIDC tokens. The principle is the same: replace long-lived secrets with short-lived, cryptographically-verifiable identity assertions. Secrets Management covers the broader problem of eliminating static credentials from infrastructure.

Trade-offs

Common Pitfalls

Exercise

Design the auth system for a SaaS product with: a web SPA, iOS/Android mobile apps, a public developer API, internal microservices, and SSO with enterprise customers (Okta, Azure AD). For each client type, specify: the OAuth grant, token storage strategy, token lifetimes, refresh rotation policy, and how you revoke all tokens when a user is deactivated.

Key Takeaways

• OAuth 2.0 delegates authorization; OpenID Connect adds authentication. Use OIDC for “sign in with” flows.
• Authorization Code + PKCE is the only grant you should use for new user-facing applications. OAuth 2.1 makes this official. ²
• Access tokens are short-lived (5 to 60 min) and for APIs. ID tokens are for login and audience-bound to the client. Never confuse them.
• Refresh token rotation with reuse detection catches theft: a replayed old token revokes the entire family.
• Never store tokens in localStorage. Use the BFF pattern for SPAs.
• OIDC federation (GitHub Actions to AWS, GitLab to GCP) eliminates long-lived secrets from CI/CD. Pin trust policies to exact sub and aud values.
• The Facebook 2018 breach exposed roughly 29 million accounts’ access tokens and resulted in a 251 million EUR fine from the Irish DPC in December 2024. ⁸⁹ Token security is not optional.

Further Reading

• RFC 6749: The OAuth 2.0 Authorization Framework - The core spec. Still the starting point even for OAuth 2.1 work. Read sections 4.1 (Auth Code) and 10 (Security Considerations) first.
• RFC 7636: Proof Key for Code Exchange (PKCE) - The extension that rescued the Authorization Code flow for public clients. Short, readable, and essential.
• RFC 9700: OAuth 2.0 Security Best Current Practice - The consolidated security BCP (January 2025). Required reading for anyone shipping OAuth in production.
• RFC 9449: OAuth 2.0 Demonstrating Proof of Possession (DPoP) - Binding tokens to client key pairs at the application layer. The future of sender-constrained tokens.
• OpenID Connect Core 1.0 - The OIDC spec. Focus on sections 2 (ID Token) and 3.1 (Authorization Code Flow).
• Eran Hammer, “OAuth 2.0 and the Road to Hell” - The 2012 critique that shaped OAuth 2.1. Understand what went wrong to appreciate why the BCP exists.
• Datadog Security Labs: GitHub-to-AWS Keyless Authentication Flaws - Real-world OIDC federation misconfigurations. Read before configuring any CI/CD trust policy.
• oauth.net - Aaron Parecki’s readable reference site. The best non-RFC introduction to OAuth concepts and flows.

Flashcards

References