OAuth 2.0 and OpenID Connect login: authorization code with PKCE

OAuth authorizes access to a resource; OpenID Connect adds an authentication layer and ID Token. The client application, authorization server, browser, and resource server have different responsibilities. A code returned through the browser is an input to a pending transaction, not proof by itself that the browser owns the account named by a later token.

Before redirecting, create a transaction bound to the initiating browser session: expected issuer, redirect URI, random state, PKCE verifier, OIDC nonce, creation time, and intended safe return destination. Store secrets server-side or in an appropriately protected transaction mechanism. The browser’s callback parameters must not overwrite those expectations.

State correlates the callback to the initiated flow, PKCE binds code redemption to possession of a transaction secret, and nonce binds the ID Token to the authentication request. They are related defenses with distinct inputs. Using the same constant value for every login removes their transaction-specific value.

First, generate a high-entropy PKCE verifier and derive the S256 challenge: BASE64URL(SHA256(verifier)) without padding. Send the challenge, state, nonce, fixed redirect URI, and required scope to the expected authorization endpoint. The verifier stays with the client until the token request.

Second, receive the callback and locate the unexpired browser-bound transaction. Validate state and the iss response parameter defined by RFC 9207, where the provider sends it, before exchanging the code. Use the expected token endpoint from trusted issuer configuration, not a URL supplied in callback data. A transaction for issuer A must not become a token request to issuer B.

Third, redeem the code with the original redirect URI and verifier. The authorization server checks the code’s client and redirect bindings, expiry, single use, and PKCE challenge. A stolen code alone should not be redeemable without the verifier. Client authentication, where applicable, is an additional control rather than a replacement for those bindings.

Fourth, validate the ID Token using the expected issuer’s trusted keys and configured algorithm policy. Check issuer, audience/client binding, time claims, and the transaction nonce according to the chosen OIDC profile. Only then map the stable pair of issuer and subject to a local account and establish a fresh local session.

Finally, consume the transaction so a duplicate callback cannot create another login. If two callbacks race, a check-then-delete pattern may allow both through; use an atomic state transition. Retain enough diagnostic correlation to explain a failure without storing authorization codes, verifiers, or whole tokens in logs.

RFC 9700, the OAuth 2.0 security best current practice published in January 2025, turns years of attacks into requirements. The table pairs each common attack with the control that stops it; the attacks guide at /domains/identity-crypto/authentication/oauth-oidc-attacks/ covers each one in depth.

Do not identify users solely by an email claim. Emails can change, may have differing verification semantics, and are not a stable cross-issuer identifier. Account linking requires proof of control over the existing local account and the new external identity; a matching email is not that proof.

An ID Token is intended for the client’s authentication processing. An API access token is intended for a resource server. Similar JWT syntax does not make them interchangeable. The API must enforce its own audience and authorization policy rather than accepting any signed token returned during login; the JWT validation lab at /labs/token-validation/ practices that check.

Concurrent tabs need separate pending transactions so one tab does not overwrite another’s nonce or verifier. A lost transaction cookie should produce a bounded restart, not a bypass. Native applications follow RFC 8252 instead of copying a web-client callback design: use the system browser rather than an embedded web view, redirect to a claimed HTTPS URL, a private-use scheme or a loopback address, and always use PKCE.

Protocol libraries reduce implementation risk, but configuration still supplies the trusted issuer, client identity, redirect URI, algorithms, and token-purpose expectations. A library that verifies a signature cannot infer the account-linking rule or whether a return URL is allowed.

RFC 10017, OAuth 2.0 for Browser-Based Applications (BCP 212, August 2026), compares three architectures. A backend for frontend (BFF) runs the OAuth flow as a confidential client and gives the browser only an HttpOnly session cookie. A token-mediating backend obtains tokens but hands access tokens to the browser. A browser-only client runs the whole flow in JavaScript and is the most exposed, because any injected script can use or exfiltrate its tokens.

Prefer the BFF. If tokens must reach the browser, keep them out of localStorage, make access tokens short-lived and sender-constrained with DPoP, and rotate refresh tokens with reuse detection. Confidential clients should authenticate with private_key_jwt or mutual TLS, and can send pushed authorization requests (PAR, RFC 9126) so request parameters cannot be altered in the browser.

The library performs the protocol checks; your code keeps one transaction per browser session and consumes it once. Tested with openid-client 6.8.8 on Node.js 26 against a local HTTPS provider: an ordinary login succeeds once, while a replayed callback, a swapped state, a foreign iss, an ID token carrying another transaction’s nonce, a code redeemed without its verifier and discovery metadata naming another issuer all fail.

import * as client from 'openid-client';

// Confidential web client. Discovery pins the issuer; the library refuses metadata for another one.
const config = await client.discovery(new URL('https://id.example'), 'client-7', process.env.CLIENT_SECRET);
const REDIRECT_URI = 'https://app.example/callback'; // registered exactly, no wildcards

// 1. Start: keep the transaction in the server-side session of this browser.
export async function startLogin(session) {
  const verifier = client.randomPKCECodeVerifier();
  session.login = {verifier, state: client.randomState(), nonce: client.randomNonce()};
  return client.buildAuthorizationUrl(config, {
    redirect_uri: REDIRECT_URI,
    scope: 'openid email',
    code_challenge: await client.calculatePKCECodeChallenge(verifier), // S256
    code_challenge_method: 'S256',
    state: session.login.state,
    nonce: session.login.nonce,
  });
}

// 2. Callback: checks state, the RFC 9207 iss parameter, PKCE, and the ID token's
// signature, issuer, audience, expiry and nonce before returning anything.
export async function finishLogin(session, callbackUrl) {
  const pending = session.login;
  delete session.login; // single use, even when the exchange fails
  if (!pending) throw new Error('no login in progress');
  const tokens = await client.authorizationCodeGrant(config, callbackUrl, {
    pkceCodeVerifier: pending.verifier,
    expectedState: pending.state,
    expectedNonce: pending.nonce,
    idTokenExpected: true,
  });
  const {iss, sub} = tokens.claims(); // map (iss, sub) to the local account, never the email
  return {iss, sub};
}

Authlib's Flask client keeps state, nonce and the PKCE verifier in the Flask session and checks them in authorize_access_token, which also verifies the ID token's signature against the provider's JWKS, its issuer against the discovery document, the audience, the expiry and the nonce. Your code still has to insist on a verified ID token, start a fresh session and map the account by issuer and subject. Flask's default session is a signed cookie the browser can read, so use a server-side session store in production. Tested with Authlib 1.8.0 and Flask 3.1.3 on Python 3.14 against a local provider: a login succeeds once and sends the verifier that matches the S256 challenge, while a replayed callback, a forged state, an ID token carrying another login's nonce and an ID token from another issuer all fail without creating a session.

import os

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

ISSUER = os.environ.get("OIDC_ISSUER", "https://id.example")
app = Flask(__name__)
app.secret_key = os.environ["FLASK_SECRET_KEY"]
oauth = OAuth(app)
oauth.register(
    "idp",
    client_id="client-7",
    client_secret=os.environ["CLIENT_SECRET"],
    # Discovery supplies the endpoints and JWKS; Authlib checks the ID token's iss against it.
    server_metadata_url=f"{ISSUER}/.well-known/openid-configuration",
    client_kwargs={"scope": "openid email", "code_challenge_method": "S256"},  # PKCE
)


@app.get("/login")
def login():
    # Stores state, nonce and the PKCE verifier in this browser's session, then redirects.
    return oauth.idp.authorize_redirect("https://app.example/callback")  # registered exactly


@app.get("/callback")
def callback():
    # Checks and consumes state, redeems the code with the verifier, then verifies the ID
    # token's signature, issuer, audience, expiry and nonce. Any failure raises.
    token = oauth.idp.authorize_access_token()
    claims = token.get("userinfo")
    if claims is None:
        abort(401)  # no verified ID token, no login
    session.clear()  # a fresh session for the signed-in user
    session["account"] = [claims["iss"], claims["sub"]]  # map by (iss, sub), never by email
    return redirect("/")

Spring Boot reads the client registration from properties: spring.security.oauth2.client.provider.id-example.issuer-uri=https://id.example makes Spring fetch the discovery document and check that its issuer matches, and spring.security.oauth2.client.registration.id-example.client-id, client-secret and scope=openid,email complete it. Register the default redirect URI, https://app.example/login/oauth2/code/id-example, exactly: exact matching is what stops redirect-URI manipulation and open-redirect abuse of the callback. Since Spring Security 7 a confidential client sends PKCE by default (ClientSettings.requireProofKey is true); in 6.x that setting was off by default.

AccountRepository stands for your own account store. Tested with Spring Boot 4.1.1 (Spring Security 7.1.1) on JDK 21 against a local provider: the authorization request carries code_challenge_method=S256, state and nonce; the token request carries the matching verifier; a login maps the account by issuer and subject and changes the session; and a replayed callback, a swapped state and an ID token with another login's nonce all end in a login error.

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.oauth2.client.oidc.userinfo.OidcUserRequest;
import org.springframework.security.oauth2.client.oidc.userinfo.OidcUserService;
import org.springframework.security.oauth2.client.userinfo.OAuth2UserService;
import org.springframework.security.oauth2.core.oidc.user.OidcUser;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
class LoginConfig {

    @Bean
    SecurityFilterChain web(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests(requests -> requests.requestMatchers("/", "/error").permitAll()
                        .anyRequest().authenticated())
                // Authorization code flow. Spring Security 7 adds PKCE (S256), state and, for the
                // openid scope, a nonce, and verifies the ID token before the user service runs.
                .oauth2Login(Customizer.withDefaults());
        return http.build();
    }

    @Bean
    OAuth2UserService<OidcUserRequest, OidcUser> oidcUserService(AccountRepository accounts) {
        OidcUserService delegate = new OidcUserService();
        return request -> {
            OidcUser user = delegate.loadUser(request); // signature, iss, aud, exp and nonce already checked
            // Key the local account on (iss, sub); an email address can change or be reassigned.
            accounts.findOrCreate(user.getIssuer().toString(), user.getSubject());
            return user;
        };
    }
}

Test the ordinary flow and independently alter state, verifier, nonce, issuer, audience, and callback age. A failure must create no local authenticated session. Replaying a consumed callback must fail; a second legitimate tab with its own pending transaction must still succeed.

The exercise supplies protocol observations rather than actual token signatures. Use it to rehearse decision ordering. For an integration test, exercise the chosen library against a controlled issuer and its real signed tokens, as the Node.js example above was, and document that separately from checking claims in a JSON example.

Repair the code

OAuth redirect and PKCE lab: Match redirect URIs and verify PKCE

Sources & further reading

The standards, specifications and documentation behind the guidance above. Each is the evidence for a claim on this page; consult it for detail beyond the defaults and versions listed here.

1. RFC 9700: OAuth 2.0 security best current practice. January 2025 (BCP 240).
2. OpenID Connect Core 1.0. Final, incorporating errata set 2.
3. RFC 7636: PKCE. September 2015.
4. RFC 9207: Authorization server issuer identification. March 2022.
5. RFC 9449: DPoP. September 2023.
6. RFC 10017: OAuth 2.0 for browser-based applications. August 2026 (BCP 212).
7. RFC 8252: OAuth 2.0 for native apps. October 2017 (BCP 212).
8. OWASP OAuth 2.0 Cheat Sheet
9. openid-client for Node.js
10. Authlib: Flask OAuth client. Authlib 1.8.0.
11. Spring Security: OAuth 2.0 login and PKCE for confidential clients

Reference information

Tags

Authentication and sessionsOAuth and OpenID Connect

SDLC phase

Development

Role

Developers

ASVS 5.0.0 requirements

v5.0.0-10.1.1 · v5.0.0-10.2.1 · v5.0.0-10.2.2 · v5.0.0-10.4.1 · v5.0.0-10.4.5 · v5.0.0-10.5.1 · v5.0.0-10.5.2 · v5.0.0-10.5.4

Download this guide as Markdown

Continue exploring