What is pkce.mdx?

pkce.mdx is a documentation file written in MDX format that explains the PKCE (Proof Key for Code Exchange) extension to the OAuth 2.0 authorization flow. MDX combines regular Markdown with embedded JSX components, allowing the guide to include interactive examples, code snippets, and visual aids while still being easy to read as plain text.

Let's break it down

PKCE adds two extra parameters-code_challenge and code_verifier-to the standard OAuth 2.0 authorization code flow. The client first creates a random code_verifier, hashes it to produce a code_challenge, and sends the challenge to the authorization server. When the client later exchanges the authorization code for an access token, it must send the original code_verifier. The server hashes the verifier and checks that it matches the original challenge, proving that the same client that started the flow is completing it.

Why does it matter?

PKCE prevents a class of attacks called “authorization code interception.” Without PKCE, a malicious app could steal the short‑lived authorization code from the redirect URL and exchange it for a token. By requiring the secret code_verifier that only the legitimate client knows, PKCE makes the exchange secure even for public clients (e.g., mobile or single‑page apps) that cannot keep a client secret.

Where is it used?

PKCE is now the recommended default for all OAuth 2.0 public clients. You’ll find it in:

  • Mobile apps (iOS, Android) using Google, Facebook, or custom identity providers.
  • Single‑page applications (React, Angular, Vue) that run entirely in the browser.
  • Native desktop applications (Electron, .NET, Java) that cannot store a confidential client secret.
  • Some server‑side flows where extra security is desired.

Good things about it

  • Improved security for apps that cannot keep a secret.
  • No extra server configuration needed; the same authorization endpoint supports PKCE.
  • Backwards compatible - if a server doesn’t understand PKCE, it simply ignores the extra parameters.
  • Easy to implement with many libraries already handling the code_challenge generation and verification.
  • Works with existing OAuth 2.0 providers (Google, Microsoft, Okta, Auth0, etc.) without additional setup.

Not-so-good things

  • Slightly more complex client code because the app must generate a random verifier and store it temporarily.
  • Potential for implementation errors (e.g., using the wrong hashing method) which can cause authentication failures.
  • Does not replace the need for a client secret in confidential client scenarios; it only protects public clients.
  • Older or custom authorization servers may not support PKCE, requiring fallback or server upgrades.