OAuth 2.0 & OpenID Connect Explained

The four roles

Key terms

• Access token: the "valet key" the client sends to the API in an HTTP header: Authorization: Bearer <token>. "Bearer" means whoever holds the token can use it. It is short-lived (minutes to an hour).
• Refresh token: a token used to get new access tokens without asking the user again. It lives for a long time, must be stored safely, and can be revoked (cancelled) (post 49).
• Scopes: a scope is a name for what the token allows, such as photos.read, calendar.readonly or repo:status. Ask for the fewest scopes you need.
• Consent: the screen where the user approves the requested scopes.
• Redirect URI: the address where the authorization server sends the user back after approval. You must register it in advance, and the server checks that it matches exactly.
• Client ID / client secret: these identify the app. The client ID is public. The client secret is like the app's password. Confidential clients (server-side apps) can keep a secret. Public clients (mobile apps, single-page apps) cannot, because anyone can extract anything that is in their code.

The main flow: Authorization Code + PKCE

A "flow" is the set of steps an app follows to get a token. This is the recommended flow for almost every app: server-side web apps, single-page apps and mobile apps.

Why two steps ("code first, then token")? The authorization code travels through the browser, in the redirect URL. This is a risky place. The code is short-lived and can be used only once, so it is useless on its own. The tokens are fetched in a separate, direct request from the client to the authorization server.

What PKCE adds. PKCE (Proof Key for Code Exchange, said "pixy") is an extra step that protects against an attacker who steals the authorization code. For example, a malicious app on a phone may register the same redirect address as your app.

• The client creates a random code_verifier and sends only its hash (code_challenge) at the start. A hash is a one-way fingerprint: you cannot get the verifier back from it.
• To swap the code for tokens, the client must present the original verifier.
• An attacker who has only the stolen code cannot complete the exchange.

PKCE was first made for mobile apps. Now it is recommended for all clients, including server-side ones.

What state does. The state parameter is a random value. The client creates it and checks it when the user comes back. It stops CSRF-style attacks (forged requests), where an attacker tricks your app into accepting their authorization code and linking their account.

Client Credentials: machine-to-machine

Use this flow when no user is involved. For example, a backend service calls another company's API, or one internal service calls another:

The service logs in as itself. Keep its secret safe (post 51). Even better, use private-key JWT client authentication (the service signs a token with its private key) or mTLS (both sides show certificates) instead of a shared secret.

Device Authorization flow

Use this flow for devices that have no browser or easy keyboard, like smart TVs, game consoles and command-line tools:

That's why you log into streaming apps on a TV by typing a short code on your phone.

Deprecated flows: don't use these

• Implicit flow: tokens were returned directly in the browser URL. They leaked through browser history, logs and referrer headers (a header that tells a site which page the user came from). It is replaced by Authorization Code + PKCE.
• Resource Owner Password Credentials: the app collects the user's password and sends it to the auth server. This defeats the whole point of OAuth. Do not use it.

The OAuth 2.0 Security Best Current Practice (RFC 9700) and the OAuth 2.1 draft put these rules together: PKCE for everyone, no implicit or password grants, exact redirect URI matching, and tokens that are short-lived, tied to the sender, or rotated. (An RFC is an official internet standards document. A "grant" is another word for a flow.)

Access token formats

• Opaque tokens: random strings with no meaning that the API can read. The API must ask the authorization server "is this token valid, and what are its scopes?" This is called token introspection. Opaque tokens are easy to revoke, but they add one call per request (you can cache the answer).
• JWT access tokens: these carry their own data and are signed (post 49). The API verifies them locally using the authorization server's public keys, which it gets from the server's JWKS endpoint (a URL that lists the keys). This is fast, but revoking a token relies on short expiry.

The API must validate every token:

• the signature (for JWTs),
• expiry (exp),
• issuer (iss): is it from our authorization server?
• audience (aud): was it issued for this API? A token meant for another API must be rejected.
• scopes: does this token allow this action?

OpenID Connect: adding login

OAuth alone does not tell the client who the user is. An access token is meant for the API, not for the client to read. Early "Login with X" features misused access tokens to find out who the user was, and this caused security bugs. OpenID Connect (OIDC) fixes this.

What OIDC adds:

• The openid scope: if you ask for it, you are saying "I want to log the user in".
• The ID token: a JWT for the client that describes the user who logged in. Here is an example. The arrow note is only for explanation:

{  "iss": "https://accounts.google.com",  "sub": "110169484474386276334",      ← stable, unique user ID at this provider  "aud": "your-client-id",  "exp": 1803000000,  "iat": 1802996400,  "nonce": "n-0S6_WzA2Mj",  "email": "asha@example.com",  "email_verified": true,  "name": "Asha Kulkarni"}

• The userinfo endpoint: a URL where you can get more profile details by using the access token.
• Discovery: a standard URL (/.well-known/openid-configuration) lists the provider's endpoints, supported features and JWKS keys, so libraries can configure themselves automatically.
• The nonce: a random value that the client sends and then looks for in the ID token. It prevents replay attacks, where an attacker re-uses an old token.

ID token vs access token:

Identify users by iss + sub, not by email. Emails can change, and the same email can exist at different providers. The sub value stays the same for one user at one provider.

Security checklist

• ✅ Use Authorization Code + PKCE (and state, and nonce for OIDC).
• ✅ Register exact redirect URIs, with no wildcards. An open redirect (a page that sends users to any address it is given) is a classic way to steal tokens.
• ✅ Request minimal scopes. Ask for more only when the user really needs the feature. This is called "incremental consent".
• ✅ Keep access tokens short-lived. Rotate refresh tokens and store them securely.
• ✅ Validate every token: signature, exp, iss, aud and scopes.
• ✅ For single-page apps, prefer a BFF (post 13) that keeps tokens on the server, giving the browser only an HttpOnly session cookie.
• ✅ Protect client secrets, or avoid them with private-key JWT or mTLS client authentication.
• ✅ Let users see and revoke connected apps.
• ✅ Use a well-tested library or identity provider. Do not write OAuth yourself from scratch.

Build or buy?

Running your own authorization server means you must handle login, MFA, passkeys, account recovery, token signing, key rotation (changing keys regularly), consent, security patches and legal rules (compliance). So most teams use one of these instead:

• managed identity providers (another company runs them for you): Auth0/Okta, Microsoft Entra ID, AWS Cognito, Google Identity Platform, Firebase Auth, Clerk,
• open-source servers that you run yourself: Keycloak, Ory, Authentik, Zitadel,
• social login: Google, Apple, Microsoft, GitHub.