Before we touch Keycloak at all, let’s build a rock-solid mental model of what PKCE actually is.

PKCE stands for Proof Key for Code Exchange. It is an extension to the OAuth 2.0 Authorization Code flow, defined in a specification called RFC 7636. Its entire job is to prove that the application asking to exchange an authorization code for tokens is the same application that originally started the login process — not an impostor who intercepted the code along the way.

To understand why this PIN is necessary, we need one more term: OAuth 2.0. OAuth 2.0 is an authorization framework — a set of rules that let one application (say, a mobile app) obtain limited access to a user’s data on another system (say, a company’s identity server) without ever seeing the user’s password. The most common way this happens is the Authorization Code flow: the app redirects the user to a login page, the user logs in, and the login server sends back a short-lived “authorization code.” The app then trades that code for access tokens and ID tokens behind the scenes.

The authorization code by itself was never meant to be a secret that stays hidden forever — it travels through a browser redirect, which is a relatively public path (think of it as being written in chalk on a sidewalk that anyone can glance at). If a malicious app or process on the same device can grab that code before the legitimate app does, it can attempt to exchange it for tokens and effectively steal the login session. PKCE was invented specifically to prevent this.

Where does Keycloak come in? Keycloak is an open-source Identity and Access Management (IAM) server built by Red Hat. It plays the role of the “identity server” in the story above: it hosts login pages, manages user accounts, issues tokens, and — importantly for us — enforces PKCE rules on behalf of every application (“client,” in Keycloak’s vocabulary) that is registered with it. Keycloak supports PKCE natively; an administrator simply configures a client to require it, and Keycloak’s Authorization Endpoint and Token Endpoint handle the rest.

To appreciate PKCE, we have to understand the attack it was built to stop.

In the early days of OAuth 2.0, “confidential clients” — typically server-side web applications — were given a client secret: a password-like value known only to the app’s backend server and the identity provider. When exchanging an authorization code for tokens, the app would also send this client secret to prove its identity. Since the secret never left the server, it was safe from prying eyes.

But mobile apps and single-page JavaScript applications don’t have a safe place to hide a secret. A client secret bundled inside a mobile app’s binary can be extracted with basic reverse-engineering tools. A secret embedded in JavaScript running in a browser is visible to anyone who opens the browser’s developer tools. These are called public clients — clients that structurally cannot keep a secret. Without a client secret to distinguish “trusted app” from “impostor app,” public clients were exposed to a specific attack.

This same class of risk applies more broadly than just mobile deep links. Any environment where an authorization code might be observed or logged along its journey — browser history, proxy logs, referrer headers, or a compromised network — benefits from PKCE’s extra proof step. That is why the OAuth working group eventually recommended PKCE for essentially all Authorization Code flows, not only public clients.

It is worth being precise about what PKCE does not do. It does not encrypt traffic (that’s TLS’s job). It does not replace login credentials or multi-factor authentication. It does not stop every kind of attack — for example, it does nothing against a fully compromised device where an attacker can read the legitimate app’s memory. What it does extremely well is close one very specific, very common gap: proving that the party redeeming an authorization code is the same party that requested it.

Let’s zoom out and see where PKCE fits inside Keycloak’s overall architecture.

Keycloak is organized around a small number of core concepts, and understanding them makes PKCE much easier to place.

Inside a Keycloak client’s settings, there is a setting typically labelled something like “Proof Key for Code Exchange Code Challenge Method.” An administrator can set this to S256 (the recommended SHA-256-based method), plain (a weaker method kept mostly for legacy compatibility), or leave it unset to make PKCE optional for that client. Modern guidance strongly favors S256 and, for public clients, making PKCE mandatory rather than optional.

Under the hood, Keycloak’s Authorization Endpoint and Token Endpoint are just parts of a larger authentication and token-issuance pipeline that also includes authenticators (username/password forms, OTP, WebAuthn), the realm’s session store, and the token issuance logic that eventually mints signed JSON Web Tokens (JWTs). PKCE slots in as a validation step that happens strictly between the authorization request and the token exchange — it does not touch how the user actually authenticates (their password, OTP, biometrics, and so on remain unaffected).

graph TD
    A[Client App] -->|1: Authorization Request + code_challenge| B[Keycloak Authorization Endpoint]
    B -->|2: Redirect with login page| C[User Browser]
    C -->|3: User logs in| B
    B -->|4: Redirect back with authorization code| A
    A -->|5: Token Request + code_verifier| D[Keycloak Token Endpoint]
    D -->|6: Verify verifier against stored challenge| D
    D -->|7: Access Token + ID Token| A
        

Notice that the code challenge is submitted at step 1 and the code verifier is submitted at step 5 — two completely separate HTTP requests, potentially seconds or minutes apart, and possibly even from different network paths. Keycloak’s job is to remember the challenge tied to that specific authorization code, and later check that the verifier presented at token exchange time actually matches it.

Now let’s walk through the entire flow in careful, ordered detail.

sequenceDiagram
    participant App as Client App
    participant Browser
    participant KC as Keycloak
    App->>App: Generate code_verifier
    App->>App: Derive code_challenge = SHA256(code_verifier)
    App->>Browser: Redirect to Authorization Endpoint (code_challenge, method=S256)
    Browser->>KC: Authorization Request
    KC-->>Browser: Show login page
    Browser->>KC: Submit credentials
    KC->>KC: Store code_challenge with session
    KC-->>Browser: Redirect back with authorization_code
    Browser->>App: Deliver authorization_code
    App->>KC: Token Request (code, code_verifier)
    KC->>KC: Hash code_verifier, compare to stored code_challenge
    KC-->>App: Access Token + ID Token (if match)
        

Let’s go one level deeper into the cryptographic mechanics that make this trustworthy.

The security of PKCE rests on one simple mathematical property of cryptographic hash functions like SHA-256: they are one-way. Given an input, it’s trivial to compute the hash output. But given only the output, it is computationally infeasible to work backward and discover the original input. This is the same property that lets websites store password hashes instead of the passwords themselves.

This one-way property is exactly why sending the code challenge over a semi-public channel (the browser redirect) is safe: even if an attacker captures the code challenge, they cannot reverse it to discover the code verifier. Only the real app — which generated the verifier and kept it in private memory — can produce the matching value later.

Keycloak’s Token Endpoint performs the verification server-side, inside its authentication/token issuance pipeline, as part of validating the token request before minting any tokens. If the client’s configuration requires PKCE and no code_verifier is supplied, or the recomputed hash doesn’t match the stored challenge, Keycloak rejects the request with an error and issues no tokens whatsoever. This rejection happens before any token signing or session promotion occurs, so a failed PKCE check has zero side effects beyond the failed attempt itself.

There is also a subtlety worth understanding: the code verifier must have enough randomness (entropy) to resist guessing. The specification calls for at least 43 characters generated by a cryptographically secure random number generator, pulled from a large enough character set. A short or predictable verifier (for example, based on a timestamp) would undermine the whole mechanism, because an attacker could simply guess or brute-force it within the authorization code’s short lifetime.

Let’s trace the lifecycle of every PKCE-related value from birth to disposal.

Every value involved in a PKCE exchange has a short, well-defined lifespan. Understanding this lifecycle helps explain why the mechanism is both secure and lightweight.

Because the code verifier lives only in the requesting app’s memory and is never written to a log, a cookie, or local storage in a properly implemented client, there is no persistent artifact for an attacker to later retrieve — even if they compromise the device after the login flow has completed. This “ephemeral by design” property is one of the quieter but important security benefits of PKCE.

graph LR
    A[Verifier Created] --> B[Challenge Derived]
    B --> C[Challenge Sent to Keycloak]
    C --> D[Login Completed]
    D --> E[Authorization Code Issued]
    E --> F[Verifier Sent to Token Endpoint]
    F --> G{Hash Match?}
    G -->|Yes| H[Tokens Issued, Code + Challenge Discarded]
    G -->|No| I[Request Rejected, No Tokens Issued]
        

It is also important that authorization codes bound to a code challenge cannot be redeemed without the verifier — even by the legitimate app itself — if that app crashes or restarts and loses the verifier from memory. In that scenario, the app must simply restart the login flow from scratch, generating a fresh verifier and challenge pair. This is an intentional trade-off: strict single-attempt exchange in return for strong protection against theft.

A side-by-side comparison clarifies exactly what changes when PKCE is added.

Notice that PKCE does not replace the client secret for confidential clients — it complements it. A confidential client configured for PKCE in Keycloak still sends its client secret and a code verifier at token-exchange time, giving two independent layers of proof rather than one.

No mechanism is free of trade-offs. Let’s weigh PKCE honestly.

In practice, the advantages heavily outweigh the costs for almost every application. The “cost” of PKCE is a few extra lines of standard library code; the benefit is closing a well-documented, historically exploited attack path. This is why Keycloak — like most modern identity providers — makes PKCE trivial to enable through a simple client configuration toggle rather than requiring custom development.

PKCE is one layer in a broader security posture. Let’s place it in context.

A frequent point of confusion is the relationship between PKCE and the state parameter. They are complementary, not competing. The state parameter protects the browser side of the flow — ensuring the redirect back to the app corresponds to a request the app actually initiated, preventing cross-site request forgery style attacks. PKCE protects the token exchange side — ensuring whoever redeems the code is the same party that started the flow. A well-configured Keycloak client, and a well-implemented app, uses both together.

Enabling PKCE is only half the job — observing it in production matters too.

Keycloak exposes authentication and token events through its event logging system, which administrators typically forward to a centralized logging or SIEM (Security Information and Event Management) platform. From a PKCE standpoint, the events worth watching closely are token exchange failures, since a spike in these can be an early signal of an attempted authorization code interception attack, a misconfigured client, or a broken client-side implementation.

Beyond Keycloak’s own event stream, application-side logging on the client also matters — but with a firm boundary. Applications should log that a PKCE exchange succeeded or failed, and perhaps a correlation/request ID, but should never log the verifier or challenge values themselves, since that would recreate exactly the leak risk PKCE is designed to avoid.

Beyond the core mechanics, a few recurring patterns show up in real deployments.

A concise checklist for teams rolling PKCE out across their Keycloak-protected applications.

PKCE is not a theoretical construct — it underpins login flows people use every day.

Across all these examples, the common thread is the same: whenever an application cannot safely hold a long-lived secret, or whenever the authorization code might travel through an environment where interception is plausible, PKCE provides a lightweight, standardized, and now near-universal answer.

Quick answers to the questions that come up most often when teams first adopt PKCE in Keycloak.

It’s not strictly required, but it is still recommended. PKCE adds an independent layer of protection against authorization code interception that a client secret alone does not fully address, since the secret protects the token exchange call’s authenticity but not the code’s journey through the browser redirect.

Keycloak rejects the token request outright. No access token, ID token, or refresh token is issued, and the authorization code is treated as consumed, so the client must restart the entire login flow from the beginning with a fresh verifier and challenge.

No. PKCE is specific to the Authorization Code grant, which involves a user redirecting through a browser. The Client Credentials grant is a machine-to-machine flow with no user or browser involved, so there is no authorization code to protect in the first place.

It started there, but current best practice extends it to single-page applications and even traditional confidential web clients, because the protection it adds is cheap and the risk it mitigates — authorization code interception — can occur in more contexts than originally anticipated.

No. Generating a random verifier and computing a SHA-256 hash are both extremely fast local operations, and the resulting values simply piggyback on the authorization and token requests that already exist in the flow — no extra network round trips are introduced.

A client secret is a long-lived, static value shared once during client registration and reused across every login. A code verifier/challenge pair is generated fresh for every single login attempt and discarded immediately after use, making it far less valuable as a target if ever exposed.

PKCE turns a historically vulnerable step in the OAuth 2.0 Authorization Code flow — the exchange of a code that briefly travels through a browser redirect — into a step that is provably tied to the exact application that started the login. In Keycloak, this is a simple client-level configuration choice with an outsized security benefit, protecting public clients like mobile apps and single-page applications that structurally cannot hold a durable secret, while still adding useful defense-in-depth for confidential clients that can.