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.0 | OpenID Connect | |
|---|---|---|
| Question | May this app call this API? | Who just signed in? |
| Gives the app | An access token | An ID token as well |
| About | Delegated authorization | Identity, 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
- The client creates a random secret and sends only its hash.
- The user signs in and consents.
- A short-lived code comes back through the browser.
- 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_secretis 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
| Token | Meant for | Job |
|---|---|---|
| Access token | The API | Authorize API calls, minutes |
| ID token | The client | Say who signed in, used once |
| Refresh token | The authorization server | Get 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
audnot checked: other apps' tokens pass- Users keyed by email: use
subwithiss - 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