Authorization Code Flow

The flow involves a series of redirects between the user's browser, the client application, and the authorization server.

1. Authorization Request: The client redirects the user to the authorization server with parameters like client_id, redirect_uri, and requested scope.
2. User Authentication & Consent: The user authenticates and grants permission to the requested scopes.
3. Authorization Grant: The server redirects back to the client with a one-time-use authorization code.
4. Token Exchange: The client's backend server exchanges the code for an access token and optionally a refresh token via a secure, server-to-server POST request.

This flow is the gold standard for traditional web applications with a backend server. The critical security feature is that the sensitive access token is never exposed to the user's browser; it is received and stored securely on the backend server. This prevents token theft through browser-based attacks. Common implementations include:

• User login on a company's internal dashboard.
• Connecting a third-party SaaS tool to a user's Google Drive or GitHub account.

The Proof Key for Code Exchange (PKCE, pronounced "pixie") extension secures the flow for public clients that cannot store a secret, such as Single-Page Applications (SPAs) and native mobile apps.

• The client creates a cryptographically random code_verifier and a derived code_challenge.
• The challenge is sent with the initial request.
• During the token exchange, the client must present the original verifier. The server validates it matches the challenge, proving the same client that initiated the flow is redeeming the code, thwarting authorization code interception attacks.

Compared to simpler flows like the Implicit Flow, the Authorization Code Flow provides superior security:

• Tokens Never in Browser: Access tokens are issued directly to the confidential client backend.
• Client Authentication: The backend can authenticate itself to the authorization server using a client_secret.
• Short-Lived Codes: The authorization code is single-use and has a very short lifespan (often minutes).
• Refresh Token Support: Allows obtaining new access tokens without user re-authentication, while keeping refresh tokens server-side.

This makes it the recommended flow for most applications by standards bodies like the IETF and OpenID Foundation.

Understanding the essential parameters is crucial for implementation:

• response_type=code: Indicates the Authorization Code Flow is being used.
• client_id & client_secret: Identify and authenticate the client application.
• redirect_uri: The URI to which the authorization server sends the user back with the code. Must be pre-registered.
• scope: Defines the permissions being requested (e.g., read:user, openid).
• state: A cryptographically random string used to maintain state between the request and callback, preventing CSRF attacks.
• code_challenge & code_verifier: PKCE parameters for public clients.

The state parameter is a critical defense against Cross-Site Request Forgery (CSRF) attacks. It is an opaque, cryptographically random value that must be:

• Generated by the client and included in the initial authorization request.
• Returned unchanged by the authorization server in the redirect.
• Validated by the client to ensure the response matches the original request. Failure to use and validate the state parameter can allow an attacker to trick a user into authorizing a malicious application.

Confidential clients (with a backend server) must authenticate to the token endpoint. Methods include:

• Client Secret Basic: Sending client_id and client_secret in the HTTP Authorization header (most common).
• Client Secret Post: Sending credentials in the POST body.
• Private Key JWT: Using signed JWTs for stronger authentication. Public clients cannot securely store a secret and must use PKCE instead. Secrets must be stored securely (e.g., environment variables, secret managers) and never exposed in client-side code.

Strict redirect URI validation prevents authorization code leakage. The authorization server must:

• Pre-register the exact, full redirect URIs for each client.
• Compare the redirect_uri parameter in the authorization request against the pre-registered list with exact string matching.
• Reject requests using non-registered URIs, open redirectors, or wildcards that could allow an attacker to intercept the authorization code.

Secure handling of tokens after issuance is essential:

• Access Tokens: Should have short lifetimes (e.g., minutes/hours) to limit exposure if leaked. Use refresh tokens for long-lived sessions.
• Refresh Tokens: Must be stored with maximum security (server-side, encrypted) as they grant long-term access. Implement refresh token rotation to detect and prevent replay attacks.
• ID Tokens: Are for the client only and should not be sent to resource servers. Validate the signature, aud (audience), and exp (expiration) claims.

Avoid these frequent security flaws:

• Insufficient Entropy: Using weak random number generators for state or code_verifier.
• Mixed Client Types: Treating a Single-Page App as a confidential client by embedding a secret.
• Missing PKCE: Using the base flow for public clients.
• Lax Redirect URI Matching: Allowing subdomain or path variations that aren't explicitly registered.
• Ignoring Token Binding: Not using mechanisms like Demonstration of Proof-of-Possession (DPoP) or mTLS to bind tokens to a specific client, mitigating token replay.

An authorization framework that enables third-party applications to obtain limited access to a user's resources on a server, without exposing their credentials. It is the standard that defines the Authorization Code Flow and other grant types.

• Core Concept: Delegated access via tokens.
• Key Roles: Resource Owner, Client, Authorization Server, Resource Server.
• Use Case: Logging into a website using your Google account.

The server that authenticates the user and issues access tokens to the client after obtaining authorization. It is the central authority in the OAuth flow.

• Primary Functions: Presents the consent screen, validates credentials, and exchanges the authorization code for tokens.
• Key Component: Hosts the /authorize and /token endpoints.
• Example: Google's OAuth 2.0 servers or Auth0.

A short-lived credential used by the client application to access protected resources on behalf of the user. It is the key output of the Authorization Code Flow.

• Format: Often a JWT (JSON Web Token).
• Lifetime: Typically expires after a short period (e.g., 1 hour).
• Usage: Sent in the Authorization: Bearer header of API requests to the Resource Server.

A long-lived credential used to obtain a new access token without requiring the user to re-authenticate. It is issued alongside the access token.

• Security: Must be stored securely by the client, as it grants persistent access.
• Flow: Sent to the Authorization Server's /token endpoint to get a fresh access token.
• Purpose: Enables better user experience and security by limiting the exposure of access tokens.

A confidential key known only to the client application and the Authorization Server. It authenticates the client's identity during the token exchange.

• Confidential Clients: Web applications with a secure backend can store this secret.
• Public Clients: Native or SPAs cannot securely store it, often using the PKCE extension instead.
• Usage: Sent in the request body when exchanging an authorization code for tokens.

An extension to the Authorization Code Flow designed to secure public clients (like mobile apps) that cannot store a client secret. It prevents authorization code interception attacks.

• Mechanism: The client creates a code verifier and a derived code challenge.
• Process: The challenge is sent initially; the verifier is sent during the token exchange to prove the request's origin.
• RFC: Defined in RFC 7636. Now recommended for all OAuth 2.0 clients.