OAuth 2.0 authorization code flow with PKCE for public clients

What it is

In the authorization code grant the browser is redirected to the authorization server, the user consents, and the server redirects back with a short-lived code, which the client exchanges for tokens at the token endpoint. A confidential client authenticates that exchange with its client secret; a public client has none, so a stolen code could be redeemed by anyone. RFC 7636 (cited) closes the gap: the client generates a code_verifier, a random string of 43 to 128 unreserved characters, sends code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier))) with code_challenge_method=S256 in the authorization request, and sends the plain code_verifier with the code at the token endpoint. The server recomputes the hash and refuses a mismatch. The RFC states that a client capable of S256 must use it; the plain method exists only for constrained clients.

Why it matters

RFC 8252 (cited) requires public native app clients to implement PKCE and authorization servers to support it, and asks native apps to use the system browser rather than an embedded web view. RFC 9700 (cited), the OAuth security best current practice, extends the requirement: public clients must use PKCE, confidential clients are recommended to, clients should not use the implicit grant (tokens in the URL fragment leak through history and referrers), refresh tokens for public clients must be sender-constrained or rotated, and redirect URIs must be compared by exact string matching (port excepted for localhost on native apps). PKCE also defends against authorization code injection, where an attacker plants a code obtained elsewhere into the victim's session.

How to apply

• Generate the verifier with a cryptographically secure random source per authorization request; store it with the state value in a place bound to the user agent (session storage for a browser app, process memory for a CLI).
• Register exact redirect URIs. For a native, CLI or desktop app, RFC 8252 describes three ways to receive the response: a private-use URI scheme, a claimed https URI, or loopback redirection (http://127.0.0.1:<port>/).
• Verify state on return, exchange the code once, and discard the verifier.
• Ask for minimal scope, keep access tokens short-lived and use refresh token rotation so a leaked refresh token is detected on reuse.
• Use a maintained client library; the flow has more edge cases (mix-up, downgrade of code_challenge_method) than fit in hand-written code.

Pitfalls

Sending code_challenge but letting the server accept token requests without a verifier (a downgrade the BCP describes). Reusing one verifier across requests. Storing refresh tokens in localStorage of a page that also runs third-party scripts. Treating an access token as proof of identity; that is what OpenID Connect ID tokens are for.

Single-page applications: prefer a backend for frontend

A browser application with a server of its own does not have to be a public client. RFC 10017 (BCP 212, 'OAuth 2.0 for Browser-Based Applications') describes the backend-for-frontend architecture, in which a small backend performs the authorization code flow as a confidential client (still with PKCE), keeps access and refresh tokens server-side and gives the browser only a same-site session cookie; the BCP strongly recommends it for business applications, sensitive applications and applications handling personal data, because script injected into the page can otherwise use or exfiltrate any token the browser holds. Use the in-browser flow described above only when there is no backend to hold the tokens, and then keep them in memory rather than in web storage.