Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 39 ยท OAuth2 Login and OIDC

PKCE Explained: Proof Key for Code Exchange

Learn PKCE for OAuth2: code verifier, S256 code challenge, the attack it prevents, how Spring Security enables it, and a runnable Java demonstration.

In the authorization code flow, a client with a secret proves who it is at the token endpoint. But a single-page app or a mobile app cannot keep a secret: its code is shipped to every user. That is a public client, and without further protection a stolen authorization code could be redeemed by an attacker. PKCE (Proof Key for Code Exchange, pronounced "pixie", RFC 7636) fixes this by binding the code to a one-time secret that only the starting client knows.

Today PKCE is recommended for every authorization code flow, including server-side apps. Spring Security enables it automatically for public clients (no client secret) and you can enable it for all clients.

The idea in three steps

  1. The client creates a random code verifier.
  2. It sends only a hash of it, the code challenge, with the authorization request.
  3. At the token request it sends the original verifier. The server hashes it and compares with the stored challenge.

An attacker who intercepts the code (for example through a malicious app registered for the same custom URL scheme) does not know the verifier, so the token exchange fails.

PKCE in three moves

Make a verifier Random, kept secret
Send the challenge SHA-256 of the verifier
Prove it later Send the verifier

Server hashes it and compares

1 / 2

Computing the challenge

For the S256 method, the challenge is BASE64URL(SHA-256(verifier)) with no padding. RFC 7636 gives a worked example, and the next program reproduces it exactly. The plain method (challenge equals verifier) exists only for clients that cannot hash: do not use it.

Java Compute a code challenge

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The verifier must be 43 to 128 characters from the unreserved set (letters, digits, -, ., _, ~). Use a cryptographically secure generator: SecureRandom, never Random.

The authorization server's side

The server stores the challenge together with the code. When the token request arrives, it recomputes the hash and compares in constant time. The stand-in below builds a tiny authorization server and shows an attacker failing.

Java Verifier check at the token endpoint (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

PKCE in Spring Security

For a confidential server-side client the setting is one line:

Java
@Bean
SecurityFilterChain chain(HttpSecurity http, ClientRegistrationRepository repo) throws Exception {
    DefaultOAuth2AuthorizationRequestResolver resolver =
        new DefaultOAuth2AuthorizationRequestResolver(repo, "/oauth2/authorization");
    resolver.setAuthorizationRequestCustomizer(OAuth2AuthorizationRequestCustomizers.withPkce());

    http.oauth2Login(login -> login
        .authorizationEndpoint(ep -> ep.authorizationRequestResolver(resolver)));
    return http.build();
}

Public clients (registered without client-secret and with client-authentication-method: none) get PKCE without extra code. If you use Spring Authorization Server, you can require it per client with ClientSettings.builder().requireProofKey(true).

Use PKCE together with state: they protect different things. PKCE binds the code to the client that asked for it, state binds the callback to the user's browser session.

Common mistakes

  • Using the plain method or a predictable verifier such as a timestamp.
  • Re-using one verifier for many logins: create a new one for every authorization request.
  • Logging the verifier or putting it in a URL. Keep it in the session or in memory only.
  • Thinking PKCE replaces a client secret for confidential clients; it adds to it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the client send with the authorization request?

    Only the hashed challenge goes through the browser. The verifier is revealed at the back-channel token request.
  2. 2. Which attack does PKCE mainly stop?

    Without the verifier a stolen code cannot be exchanged for tokens.
  3. 3. Which generator should create the code verifier?

    The verifier must be unpredictable, so a cryptographically secure source is required.
  4. 4. Which PKCE method should you use?

    S256 hashes the verifier with SHA-256. Plain sends the secret itself and defeats the purpose.

Summary

  • PKCE ties an authorization code to the client instance that requested it.
  • Challenge = Base64URL(SHA-256(verifier)); the verifier is revealed only at the token endpoint.
  • Use S256, a fresh random verifier per request, and SecureRandom.
  • Spring enables PKCE for public clients automatically and offers a customizer for all others.
  • Combine PKCE with state; they defend different steps.

Next: OIDC login and ID tokens