OAuth authorization code flow with PKCE

HOW IT FITS TOGETHER

KEY TERMS

PKCE (RFC 7636)

The client creates a random code_verifier (43-128 chars, 32 random bytes is standard), sends S256 = BASE64URL(SHA256(verifier)) as code_challenge, and later proves possession by sending the verifier to the token endpoint. RFC 9700 requires it for public clients and recommends it for confidential ones; OAuth 2.1 makes it mandatory.

state

An unguessable, per-request value bound to the user's session and echoed back on the redirect. It stops CSRF on the callback, where an attacker logs the victim into the attacker's account. PKCE also covers this for the server, but state is still how the client correlates the response with its stored request.

nonce

An OIDC value sent on the authorization request and returned inside the id_token. The client must check it matches, which binds the id_token to this login attempt and blocks replay of an id_token captured elsewhere.

id_token vs access token

The id_token is for the client: who authenticated, when, and how; its aud is your client_id. The access token is for the resource server: what the caller may do; its audience is the API. Never send an id_token to an API as a credential.

Exact redirect URI matching

The authorization server compares the redirect_uri as an exact string against registered values (the only exception is a variable port for native-app loopback URIs). Prefix or wildcard matching lets attackers steer codes to pages they control.

Refresh token rotation

Every refresh response includes a new refresh token and retires the old one. If a retired token comes back, the server cannot know which party is legitimate, so it revokes the grant. That forces re-login but caps the damage of a stolen token.

Backend for Frontend (BFF)

For SPAs, a same-site backend acts as a confidential client, keeps all tokens server-side and gives the browser only an HttpOnly session cookie. RFC 10017 (OAuth 2.0 for Browser-Based Applications) ranks it as the strongest of its three architectures.

IN YOUR STACK

function base64url(bytes: Uint8Array): string {
  let binary = "";
  for (const byte of bytes) binary += String.fromCharCode(byte);
  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
}

async function createPkcePair() {
  const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
  return { verifier, challenge: base64url(new Uint8Array(digest)) };
}

const { verifier, challenge } = await createPkcePair();
const state = base64url(crypto.getRandomValues(new Uint8Array(16)));
sessionStorage.setItem("oauth", JSON.stringify({ verifier, state }));

const url = new URL("https://auth.example.com/authorize");
url.search = new URLSearchParams({
  response_type: "code", client_id: "spa", scope: "openid profile",
  redirect_uri: "https://app.example.com/callback",
  state, code_challenge: challenge, code_challenge_method: "S256",
}).toString();
location.assign(url);

// auth.ts
import NextAuth from "next-auth";

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    {
      id: "corp",
      name: "Corp SSO",
      type: "oidc",
      issuer: "https://auth.example.com",
      clientId: process.env.AUTH_CORP_ID,
      clientSecret: process.env.AUTH_CORP_SECRET,
      checks: ["pkce", "state", "nonce"],
    },
  ],
});

// app/api/auth/[...nextauth]/route.ts
import { handlers } from "@/auth";
export const { GET, POST } = handlers;

from flask import Flask, redirect, session, url_for
from authlib.integrations.flask_client import OAuth

app = Flask(__name__)
app.secret_key = "load-from-secret-store"
oauth = OAuth(app)
oauth.register(
    "corp",
    client_id="web-app",
    client_secret="load-from-secret-store",
    server_metadata_url="https://auth.example.com/.well-known/openid-configuration",
    client_kwargs={"scope": "openid profile email", "code_challenge_method": "S256"},
)

@app.route("/login")
def login():
    return oauth.corp.authorize_redirect(url_for("callback", _external=True))

@app.route("/callback")
def callback():
    token = oauth.corp.authorize_access_token()  # checks state, sends verifier
    session["user"] = token["userinfo"]  # parsed from the validated id_token
    return redirect("/")

var conf = &oauth2.Config{
	ClientID:     "web-app",
	ClientSecret: os.Getenv("CLIENT_SECRET"),
	RedirectURL:  "https://app.example.com/callback",
	Scopes:       []string{"openid", "profile"},
	Endpoint: oauth2.Endpoint{
		AuthURL:  "https://auth.example.com/authorize",
		TokenURL: "https://auth.example.com/token",
	},
}

func login(w http.ResponseWriter, r *http.Request) {
	state, verifier := rand.Text(), oauth2.GenerateVerifier()
	saveToSession(w, r, state, verifier)
	url := conf.AuthCodeURL(state, oauth2.S256ChallengeOption(verifier))
	http.Redirect(w, r, url, http.StatusFound)
}

func callback(w http.ResponseWriter, r *http.Request) {
	state, verifier := loadFromSession(r)
	if r.URL.Query().Get("state") != state {
		http.Error(w, "state mismatch", http.StatusBadRequest)
		return
	}
	tok, err := conf.Exchange(r.Context(), r.URL.Query().Get("code"), oauth2.VerifierOption(verifier))
	// handle err; persist tok; validate tok.Extra("id_token") with an OIDC library
}

@Configuration
@EnableWebSecurity
class SecurityConfig {
  @Bean
  ClientRegistrationRepository clientRegistrations() {
    ClientRegistration corp = ClientRegistrations
        .fromIssuerLocation("https://auth.example.com")
        .registrationId("corp")
        .clientId("web-app")
        .clientSecret(System.getenv("CLIENT_SECRET"))
        .scope("openid", "profile")
        .redirectUri("{baseUrl}/login/oauth2/code/{registrationId}")
        .clientSettings(ClientRegistration.ClientSettings.builder().requireProofKey(true).build())
        .build();
    return new InMemoryClientRegistrationRepository(corp);
  }

  @Bean
  SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http.authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
        .oauth2Login(Customizer.withDefaults());
    return http.build();
  }
}

import * as WebBrowser from "expo-web-browser";
import { exchangeCodeAsync, makeRedirectUri, useAuthRequest, useAutoDiscovery } from "expo-auth-session";
import { Button } from "react-native";

WebBrowser.maybeCompleteAuthSession();

export function SignIn() {
  const discovery = useAutoDiscovery("https://auth.example.com");
  const redirectUri = makeRedirectUri({ scheme: "com.example.app", path: "oauth2redirect" });
  const [request, , promptAsync] = useAuthRequest(
    { clientId: "mobile-app", scopes: ["openid", "profile", "offline_access"], redirectUri },
    discovery,
  );

  async function signIn() {
    const result = await promptAsync();
    if (result.type !== "success" || !request || !discovery) return;
    const tokens = await exchangeCodeAsync(
      { clientId: "mobile-app", code: result.params.code, redirectUri,
        extraParams: { code_verifier: request.codeVerifier ?? "" } },
      discovery,
    );
    await saveRefreshTokenSecurely(tokens.refreshToken);
  }
  return <Button disabled={!request} title="Sign in" onPress={signIn} />;
}

WHERE IT BITES

• Sending the id_token to your own API as a bearer credential. Its audience is the client; APIs should accept only access tokens issued for them.
• Using the implicit flow or putting tokens in a browser-reachable store in an SPA. RFC 9700 says SHOULD NOT for implicit, OAuth 2.1 drops it, and RFC 10017 recommends a BFF when you have a backend.
• Registering wildcard or prefix redirect URIs, or computing redirect_uri from request headers behind a proxy, so it differs between /authorize and /token.
• Generating state once per app instead of per request, storing it unbound to the user session, or skipping nonce validation when you consume an id_token.
• Refreshing from several tabs or threads at once with rotation enabled: the second request presents a retired refresh token and revokes the whole grant. Serialize refreshes.
• Running native-app login inside an embedded web view, which lets the app read credentials and breaks SSO; RFC 8252 requires the system browser.

WHEN IT BREAKS IN PRODUCTION

• CORS fails only in production or on preflight
• A broken mobile release is already in production
• The app works in debug but crashes in release

SOURCES

• RFC 9700: Best Current Practice for OAuth 2.0 Security (opens in new tab)Checked 2026-10-07
• RFC 7636: Proof Key for Code Exchange by OAuth Public Clients (opens in new tab)Checked 2026-10-07
• The OAuth 2.1 Authorization Framework (Internet-Draft) (opens in new tab)Checked 2026-10-07
• RFC 10017: OAuth 2.0 for Browser-Based Applications (opens in new tab)Checked 2026-10-07
• RFC 8252: OAuth 2.0 for Native Apps (opens in new tab)Checked 2026-10-07
• OpenID Connect Core 1.0 (opens in new tab)Checked 2026-10-07