How OAuth and OIDC work

Two specifications, two different questions

Who the parties are, how the flows work, and which mistakes turn up most often.

Kevin Keller · kevinkeller.org

Why it matters

"Sign in with...", bearer tokens and AI agents all rest on these two

Most confusion starts because they are mentioned in the same breath. They solve different problems, and mixing them up causes real security bugs.

Two problems

OAuth hands out a key card. OIDC adds a name badge.

OAuth 2.0OpenID Connect
QuestionMay this app call this API?Who just signed in?
Gives the appAn access tokenAn ID token as well
AboutDelegated authorizationIdentity, on top of OAuth

The four parties

Every OAuth conversation has the same cast

  • Resource owner: the user whose data is involved
  • Client: the app that wants access, public or confidential
  • Authorization server: authenticates the user, issues tokens
  • Resource server: the API that accepts the token and decides

Humans signing in

Authorization code with PKCE is the default flow

  1. The client creates a random secret and sends only its hash.
  2. The user signs in and consents.
  3. A short-lived code comes back through the browser.
  4. The client redeems the code with the secret.
A stolen code is useless without that secret.

No user at all

Client credentials: the token represents the application

  • For nightly jobs, backend services and monitoring agents
  • A shared client_secret is the simplest option and the weakest
  • Better: a signed key assertion, mutual TLS or workload identity federation
  • Everything shows up as the service in audit, so keep its rights narrow

No browser on the device

Device code: convenient, and that is the risk

  • The device shows a short code, the user approves it on a phone or laptop
  • Attackers send a genuine sign-in page with a code they generated
  • The victim signs in the attacker's device
  • If you don't need this flow, block it in your identity provider

Three tokens, three jobs

Each token has its own audience

TokenMeant forJob
Access tokenThe APIAuthorize API calls, minutes
ID tokenThe clientSay who signed in, used once
Refresh tokenThe authorization serverGet new access tokens, guard like a password

Scopes are a ceiling

A token with orders:read is not "read every order"

Scopes record what the client asked for and was granted. The API still decides whether this user may touch this record.

Common mistakes

The ones that turn up most often

  • ID token sent to an API: wrong audience
  • aud not checked: other apps' tokens pass
  • Users keyed by email: use sub with iss
  • Loose redirect URIs: register exact ones
  • Implicit or password grant: gone in OAuth 2.1
  • Tokens in localStorage: XSS leaks them

The design point

Don't collapse every user into one service account.

When the backend can't tell users apart, row-level security and audit go blind. Pass the user's identity through.

The takeaway

Send the access token to the API, and always check who it was meant for.

Read the full article · Try the OIDC flow simulator

Kevin Keller · kevinkeller.org