liminfoOAuth2 Reference
Free web tool: OAuth2 Reference
Authorization Code Flow
The most commonly used flow for server-side applications. Used when the client secret can be securely stored.
Use Case
Web server applications, backend APIs
Steps
- 1. Redirect user to the auth server's /authorize endpoint
- 2. User logs in and grants permissions
- 3. Auth server redirects to redirect_uri with an authorization code
- 4. Server exchanges the code at /token endpoint for an access_token
- 5. Call APIs with the access_token
Flow Diagram
User -> App -> Auth Server (/authorize)
Auth Server -> User (Login Screen)
User -> Auth Server (Authenticate)
Auth Server -> App (code)
App -> Auth Server (/token + code + client_secret)
Auth Server -> App (access_token)Code Example
// 1. Build authorization URL
const authUrl = new URL('https://auth.example.com/authorize');
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('client_id', CLIENT_ID);
authUrl.searchParams.set('redirect_uri', REDIRECT_URI);
authUrl.searchParams.set('scope', 'openid profile email');
authUrl.searchParams.set('state', generateRandomState());
// 2. Exchange code for token in callback
const tokenRes = await fetch('https://auth.example.com/token', {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
grant_type: 'authorization_code',
code: authorizationCode,
redirect_uri: REDIRECT_URI,
client_id: CLIENT_ID,
client_secret: CLIENT_SECRET,
}),
});
const { access_token, refresh_token } = await tokenRes.json();About OAuth2 Reference
This OAuth 2.0 Reference is an interactive guide covering every major authorization flow defined in the OAuth 2.0 specification (RFC 6749) and its extensions. It covers Authorization Code Flow (the standard server-side pattern), Authorization Code Flow with PKCE (the secure pattern for SPAs and mobile apps), Client Credentials Flow (for machine-to-machine authentication), Device Authorization Flow (for TVs and IoT devices), and the OpenID Connect (OIDC) authentication layer that builds on top of OAuth 2.0. Each flow is presented with a step-by-step explanation, a plain-text flow diagram, a use case description, and copyable TypeScript/JavaScript code examples.
Web developers, mobile engineers, and security architects use this reference when implementing authentication in applications that delegate identity to an external identity provider like Google, GitHub, Auth0, Keycloak, or Azure AD. Understanding the correct flow to use is critical: using the wrong flow (such as the now-deprecated Implicit Flow) introduces security vulnerabilities. This reference explains not just how each flow works but why each step exists — for example, why PKCE's code_verifier/code_challenge mechanism prevents authorization code injection attacks in public clients.
The security best practices section covers the eight most important rules for safe OAuth 2.0 implementation: CSRF prevention with the state parameter, mandatory PKCE for public clients, HTTPS everywhere, correct token storage strategies (access tokens in memory, refresh tokens in httpOnly cookies), scope minimization, exact redirect_uri matching, avoiding the Implicit Flow, and access token expiry management. The token management section explains the roles of access tokens, refresh tokens, and OIDC ID tokens, with code showing how to refresh an access token and revoke tokens via the /revoke endpoint.
Key Features
- Authorization Code Flow — the standard pattern for server-side web apps with client_secret
- Authorization Code + PKCE — secure flow for SPAs and mobile apps using code_verifier/SHA-256 challenge
- Client Credentials Flow — M2M authentication without a user context using Basic auth header
- Device Authorization Flow — polling-based auth for smart TVs and IoT devices with user_code
- Token Management — access token, refresh token, and ID token lifecycle with refresh and revoke code
- OpenID Connect (OIDC) — scope=openid, id_token JWT decoding, userinfo endpoint, and OIDC discovery
- Security Best Practices — CSRF state parameter, PKCE, httpOnly cookies, scope minimization, no Implicit Flow
- Copyable JavaScript/TypeScript code examples for every flow and concept
Frequently Asked Questions
What is the difference between OAuth 2.0 and OpenID Connect?
OAuth 2.0 is an authorization framework — it grants an application permission to access resources on behalf of a user, but it does not authenticate the user. OpenID Connect (OIDC) is an authentication layer built on top of OAuth 2.0 that adds an ID Token (a JWT containing user identity claims like sub, name, and email). If you need to know who the user is, use OIDC. If you only need to act on their behalf, OAuth 2.0 alone may suffice.
When should I use PKCE and when is it not needed?
PKCE (Proof Key for Code Exchange) is required for all public clients — any application that cannot securely store a client_secret, such as SPAs (React, Vue, Angular), mobile apps, and desktop apps. Server-side web apps that can keep a client_secret confidential can use the standard Authorization Code Flow without PKCE, though adding PKCE even to confidential clients is increasingly recommended as a defense-in-depth measure.
What is a code_verifier and code_challenge in PKCE?
The code_verifier is a cryptographically random string generated by the client. The code_challenge is derived from it by computing SHA-256 of the code_verifier and base64url-encoding the result. The client sends the code_challenge in the /authorize request and the code_verifier in the /token request. The auth server verifies that SHA-256(code_verifier) equals the stored code_challenge, confirming the token request comes from the same client that started the auth flow.
Why is the Implicit Flow deprecated?
The Implicit Flow returned access tokens directly in the URL fragment (#access_token=...) after the authorization redirect. This exposed tokens to browser history, referrer headers, and JavaScript running on the page. Modern best practice is to use Authorization Code Flow with PKCE instead, which never exposes the access token in a URL.
Where should I store access tokens and refresh tokens in a browser app?
Store access tokens in memory (a JavaScript variable or React state) — they are short-lived so the risk of losing them on page reload is acceptable. Store refresh tokens in httpOnly, Secure, SameSite=Strict cookies so they cannot be read by JavaScript and are protected from XSS. Never store either token in localStorage or sessionStorage, as those are accessible to any JavaScript running on the page.
What is the state parameter and why is it required?
The state parameter is a random value generated by the client before the /authorize redirect and stored in sessionStorage. After the auth server redirects back to the redirect_uri, the client verifies that the state in the URL matches the stored value. This prevents CSRF attacks where an attacker tricks a victim into completing an OAuth flow with the attacker's authorization code.
What is the Device Authorization Flow and when do I use it?
The Device Authorization Flow (RFC 8628) is designed for devices that cannot open a browser or accept keyboard input — smart TVs, game consoles, CLI tools, and IoT devices. The device gets a short user_code from the auth server and displays a URL. The user visits that URL on their phone or laptop and enters the code. Meanwhile, the device polls the token endpoint until the user completes authentication.
How does the Client Credentials Flow differ from Authorization Code Flow?
Client Credentials Flow has no user involved — the application authenticates itself using its own client_id and client_secret and receives an access token representing the application, not any user. This is used for service-to-service communication, background jobs, and automated systems. Authorization Code Flow involves a user who grants permissions to the application.