OAuth 2 & OpenID Connect
Delegated access done right — authorization vs authentication, and why the difference matters.
55 minDifficulty 4/5auth · securityAI-writtenWritten by a model on 16 August 2026 and not yet read by a person. Checked automatically: schema, the pedagogical rules the hand-written material is held to, and every diagram parsed for real.
Before this
Why this exists
A calendar app wants to read your Google Calendar events. The naive approach — you type your Google password directly into the calendar app — hands a third party your actual credentials, which they could use for anything, forever, with no way for you to revoke just this one access. OAuth 2 exists specifically so you never have to do that: you authorize a SCOPED, REVOCABLE grant, never sharing your password with the app that wants access.
The mental model
OAuth 2 answers 'what is this app allowed to DO on my behalf' — authorization. OpenID Connect (OIDC) is built on top of OAuth 2 and answers a different question: 'who IS this person' — authentication. Conflating the two is the single most common source of confusion; OAuth 2 alone doesn't actually tell the app who you are, only what it's allowed to access.
How it works
The authorization code flow keeps tokens out of the browser's reach
The user is redirected to the provider (Google, say), logs in there directly, and approves specific scopes. The provider redirects back with a short-lived, single-use CODE, which the app's own SERVER (not the browser) exchanges for the actual access token via a direct, authenticated back-channel request. The browser never sees the access token itself, which protects it from being exposed via browser history, referrer headers, or a malicious script.
Scopes limit exactly what access is granted, and the user sees and approves them
A request for `scope=calendar.readonly` grants read-only access to calendar data specifically — not email, not contacts, not write access to the calendar. The consent screen the user sees during login lists exactly these scopes, so they're approving a specific, bounded grant rather than blanket access to their entire account.
An ID token (OIDC) is different from an access token (OAuth)
An access token is an opaque credential used to CALL an API on the user's behalf — the app typically can't and shouldn't inspect its contents, just present it. An ID token, which OIDC adds, is a JWT specifically containing claims ABOUT the user — their id, email, name — signed by the provider, meant to be read and verified by the app to establish who just logged in.
Tokens are short-lived, and refresh tokens renew access without re-prompting the user
An access token typically expires within an hour, limiting the damage window if it's ever leaked. A longer-lived refresh token, stored securely and used only server-side, lets the app silently obtain a new access token when the old one expires, without requiring the user to log in again every hour.
The mechanism
The user is redirected to the provider to authenticate directly with them, never sharing credentials with the app. After approving the requested scopes, the provider redirects back to the app's callback URL with a temporary authorization code. The app's server exchanges this code for tokens via a direct, server-to-server request the browser is never part of, receiving an access token (for calling APIs) and, under OIDC, an ID token (identifying the user).
sequenceDiagram participant U as User's browser participant A as App server participant P as Auth provider U->>P: redirected to log in + approve scopes P->>U: redirect back with auth code U->>A: code delivered to app's callback A->>P: exchange code for tokens (server-to-server) P->>A: access token + ID token A->>U: session established
What people get wrong
- OAuth 2 tells an application who the user is.
- OAuth 2 by itself only grants scoped ACCESS to resources — it doesn't provide verified identity information; that's specifically what OpenID Connect adds on top, via the ID token. Building a 'login with X' feature using bare OAuth 2 (without OIDC) is a well-documented source of vulnerabilities, because it conflates 'this app can access your data' with 'this is genuinely you', which OAuth 2 alone doesn't actually establish.
- 'Sign in with Google' means the app receives your Google password.
- The entire point of the flow is that the user's credentials are entered only on the provider's own login page, never seen by the third-party app — the app receives only a token representing a scoped grant, never the password itself. Users (and sometimes developers) sometimes assume 'sign in with X' works like a password manager autofilling credentials into the app, when it's structurally the opposite — the app never has the credentials at all.
- Access tokens should be decoded and inspected by the client application to check their contents.
- Access tokens are meant to be OPAQUE from the client's perspective — the client presents them to the resource server (the API being called) without needing to understand their internal format, which the resource server itself validates. This is different from ID tokens, which ARE meant to be decoded and verified by the receiving application — conflating the two token types' intended handling is a common source of confusion.
When not to use it
- You need to know WHO a user is (their identity), for a login feature.
- OpenID Connect, using the ID token — plain OAuth 2 alone doesn't provide a standardized, verifiable identity claim.
- A machine-to-machine integration with no human user involved needs to call an API.
- The OAuth 2 client credentials flow, a different grant type designed for service-to-service authorization without a user redirect step at all.
Terms
- Authorization code flow
- — The OAuth 2 flow where the browser receives a temporary code, and the app's own server exchanges it for tokens via a direct back-channel request, keeping tokens out of the browser.
- Scope
- — A specific, named permission (like calendar.readonly) that a client requests and the user approves, bounding exactly what access is granted.
- Access token
- — An opaque credential used to call an API on the user's behalf, typically short-lived.
- ID token
- — A signed JWT, added by OpenID Connect, containing verified claims about the authenticated user's identity — separate from the access token.
In an interview
What's the practical difference between an access token and an ID token, and why does an app need both for a 'login with X' feature that also calls an API?
- the ID token establishes WHO the user is (identity, via OIDC)
- the access token grants scoped permission to call an API on the user's behalf (OAuth 2)
- a login-only feature only needs the ID token; calling an API afterward requires the access token too
Can you recall it?
Why is it inaccurate to say 'OAuth 2 handles login' without qualification?