Almost every “Sign in with…” button, every API that takes a bearer token and every AI agent that acts on your behalf rests on two specifications: OAuth 2.0 and OpenID Connect. They are often mentioned in the same breath, and that is where most of the confusion starts. They solve different problems. This article separates them, walks through the flows you will meet in practice, and ends with the mistakes that turn up most often.
If you want to watch the messages fly while you read, open the OIDC flow simulator in another tab.
Two Problems, Two Specifications#
OAuth 2.0 (RFC 6749) answers the question: may this application call this API? It is about delegated authorization. The application gets an access token that lets it do specific things, without ever seeing the user’s password.
OpenID Connect (OIDC) is a thin identity layer on top of OAuth 2.0. It answers a different question: who is the user who just signed in? It adds an ID token, a signed statement about the user, plus a standard way to discover the identity provider’s settings.
A useful way to remember it: OAuth hands the application a key card for certain doors. OIDC hands it a name badge as well.
The Four Parties#
Every OAuth conversation involves four roles:
┌───────────────────┐ ┌───────────────────────┐
│ Resource Owner │ │ Authorization Server │
│ (the user) │ │ (Entra ID, Okta, │
│ │ │ Keycloak, Auth0) │
└────────┬──────────┘ └──────────┬────────────┘
│ uses │ issues tokens
▼ ▼
┌───────────────────┐ Bearer access token ┌───────────────────────┐
│ Client │ ─────────────────────▶ │ Resource Server │
│ (web app, CLI, │ │ (the API, database, │
│ agent) │ │ SaaS platform) │
└───────────────────┘ └───────────────────────┘- Resource owner: the person whose data or permissions are involved.
- Client: the application that wants access. It is a public client if it cannot keep a secret (a single-page app, a mobile app, a CLI) and a confidential client if it runs on a server that can.
- Authorization server: issues tokens after authenticating the user and checking consent. In OIDC terms this is the OpenID Provider.
- Resource server: the API that accepts the access token and decides what to allow.
The Authorization Code Flow with PKCE#
This is the flow to use whenever a human is signing in to an application. It is the default for web apps, single-page apps, mobile apps and desktop tools.
PKCE (Proof Key for Code Exchange, RFC 7636, pronounced “pixie”) was originally designed for mobile apps. Current best practice (RFC 9700, the OAuth 2.0 Security Best Current Practice) recommends it for every client, confidential ones included, and the upcoming OAuth 2.1 makes it mandatory for nearly every client (the only exception: confidential clients that already use OpenID Connect’s nonce). The challenge is BASE64URL(SHA256(verifier)), shortened to SHA256 in the diagram.
Browser / User Client App Authorization Server API
│ │ │ │
│ 1. Click "Sign in"│ │ │
│───────────────────▶│ │ │
│ │ 2. Create code_verifier │ │
│ │ (random secret) and │ │
│ │ code_challenge = │ │
│ │ SHA256(verifier) │ │
│ 3. Redirect to /authorize?response_type=code │ │
│ &client_id&redirect_uri&scope&state │ │
│ &code_challenge&code_challenge_method=S256 │ │
│◀───────────────────│ │ │
│───────────────────────────────────────────────▶│ │
│ 4. User signs in (password, passkey, MFA) │ │
│ and consents │ │
│ 5. Redirect back: redirect_uri?code=abc&state │ │
│◀───────────────────────────────────────────────│ │
│───────────────────▶│ │ │
│ │ 6. POST /token │ │
│ │ code=abc │ │
│ │ code_verifier=... │ │
│ │──────────────────────────▶│ │
│ │ │ 7. Check SHA256 │
│ │ │ (verifier) == │
│ │ │ challenge │
│ │ 8. access_token, │ │
│ │ id_token, refresh_token│ │
│ │◀──────────────────────────│ │
│ │ 9. Authorization: Bearer <access_token> │
│ │──────────────────────────────────────────────▶│Why the extra steps? The authorization code travels through the browser in a redirect, so it can leak: browser history, logs, a malicious app registered for the same custom URL scheme on a phone. PKCE makes a stolen code useless. Only the client that created the code_verifier can redeem the code, because the authorization server checks that the verifier hashes to the challenge it saw in step 3.
The state parameter is a separate protection. The client generates a random value, remembers it, and rejects the redirect in step 5 if the value does not match. That stops cross-site request forgery, where an attacker tricks your browser into completing their login.
If you request the openid scope, this flow becomes OIDC and the token response includes an ID token. Add a nonce to the authorize request too: it ends up inside the ID token and lets the client detect a replayed token.
Client Credentials: Machine to Machine#
Sometimes there is no user at all. A nightly job loads data, a backend service calls another, a monitoring agent pulls metrics. The client credentials grant covers this:
┌──────────────┐ POST /token ┌───────────────────────┐
│ Service / │ grant_type=client_credentials │ Authorization Server │
│ Job │ client authentication │ │
│ │─────────────────────────────────▶│ │
│ │ access_token (no refresh token, │ │
│ │ no ID token) │ │
│ │◀─────────────────────────────────│ │
└──────────────┘ └───────────────────────┘The client authenticates as itself. A shared client_secret is the simplest option and the weakest. Better options are a signed JWT assertion using a private key (private_key_jwt), mutual TLS, or workload identity federation, where the platform your code runs on (Kubernetes, a cloud provider, a CI system) vouches for it and no long-lived secret exists at all.
The resulting token represents the application, not a person. That matters for audit: everything the job does shows up as the service, so give it narrow permissions.
Device Code: Signing In Without a Browser#
How do you sign in on a smart TV, a CLI over SSH, or an IoT device with no keyboard? The device authorization grant (RFC 8628) splits the work across two devices:
Device (CLI, TV) Authorization Server Phone / Laptop
│ │ │
│ 1. POST /device_authorization │ │
│──────────────────────────────▶│ │
│ 2. device_code, user_code │ │
│ "WDJB-MJHT", │ │
│ verification_uri │ │
│◀──────────────────────────────│ │
│ 3. Show: "Go to example.com/device and enter WDJB-MJHT" │
│ │ 4. User opens URL, enters │
│ │ code, signs in, agrees │
│ │◀──────────────────────────│
│ 5. Poll POST /token │ │
│ (authorization_pending...) │ │
│──────────────────────────────▶│ │
│ 6. Tokens issued │ │
│◀──────────────────────────────│ │The device polls at the interval the server specifies, backing off when it receives slow_down. It is convenient, and that convenience is also the risk: attackers send victims a genuine sign-in page with a code the attacker generated, and the victim signs the attacker’s device in. Device code phishing has been used in real campaigns against Microsoft 365 tenants. If you do not need this flow, block it in your identity provider’s access policies.
Tokens: Access, ID and Refresh#
Three tokens, three different jobs:
| Token | Audience | Purpose | Typical lifetime |
|---|---|---|---|
| Access token | The API (resource server) | Authorize API calls | 5 to 60 minutes |
| ID token | The client application | Tell the client who signed in | Minutes; used once at sign-in |
| Refresh token | The authorization server | Get new access tokens silently | Hours to weeks, often rotated |
An access token may be a JWT (see How JWT Tokens Actually Work) or an opaque string the API checks through introspection. The client should treat it as opaque either way. Its format is a contract between the authorization server and the API.
An ID token is always a JWT. The client must validate it: signature against the provider’s published keys (found via the jwks_uri in /.well-known/openid-configuration), iss equal to the expected issuer, aud containing the client’s own ID, exp in the future, and nonce equal to what the client sent.
A refresh token is a high-value credential. Store it as carefully as a password, and prefer providers that rotate it on every use, so a stolen copy is detected the moment both parties try to use it.
Scopes and Claims#
Scopes are what the client asks for: openid profile email, orders:read, session:role:analyst. The user, or an administrator’s policy, approves them, and the authorization server records the result in the token, typically in a scope or scp claim.
Scopes are a ceiling, not the whole decision. The API should still check that this particular user may touch this particular record. A token with orders:read does not mean “read every order in the company”.
Claims are statements inside a token: sub (a stable user identifier), email, groups, roles. In OIDC, the scopes profile and email request standard sets of claims.
Common Mistakes#
Using the ID token to call APIs. The ID token’s audience is the client. An API that accepts it is accepting a token that was never meant for it. Send the access token.
Not validating aud. An API that checks the signature but not the audience accepts any token from the same identity provider, including one issued to a completely different application.
Identifying users by email. Emails change and get reassigned. Use sub together with iss as the stable key.
Loose redirect URIs. Wildcards or prefix matching let an attacker steer the authorization code to a page they control. Register exact URIs.
Using deprecated grants. The implicit grant returned tokens in the URL fragment, and the resource owner password grant hands the user’s password to the client. Both are gone in OAuth 2.1. Use authorization code with PKCE instead.
Tokens in browser storage. Access tokens in localStorage are readable by any script on the page, so one cross-site scripting bug leaks them. For browser apps, a backend that holds the tokens and gives the browser an HttpOnly session cookie (the “backend for frontend” pattern) is the safer design.
Long-lived bearer tokens. Anyone holding a bearer token can use it. Keep access tokens short, and where the stakes justify it, use sender-constrained tokens (DPoP, RFC 9449, or mTLS) that only work alongside a key the client holds.
Collapsing identity into a service account. When an AI agent or a web app calls a backend as one shared service account, the backend can no longer tell users apart, and row-level security and audit trails go blind. Passing the user’s identity through is harder but worth it. I walk through one such design in No Service Accounts: Langdock to Snowflake Cortex Agents as the Signed-In Employee, and a SAML-to-OAuth variant in From SAML Login to Snowflake as the User.
Try It Yourself#
A good exercise: run the OIDC simulator, copy the ID token and the access token into the JWT debugger, and write down which claims differ and why. If you can explain the aud difference to a colleague, you understand the most important idea in this article.
