The one line in an API guide that taught me PKCE
Some of the most useful things I’ve learned came from a single line in someone else’s documentation.
A few days ago, I was building the login flow for an online store. Users sign in through a central identity provider, so naturally I had their API guide open in another tab. Somewhere in there was a line about PKCE: it protects the one-time code that comes back after login, and it’s mandatory for apps that can’t store a secret.
Our app could store a secret. So, fair question: did we still need it?
It turns out the answer is yes, and the reason is one of the cleverest small ideas in web security.
first, a little foundation
To understand what PKCE fixes, we first need to see the gap it closes. That gap lives inside OAuth and OIDC, so let’s start there, briefly.
where this started
For a long time, every website wanted its own username and password. You probably remember it (you may still be living it): dozens of accounts, the same password reused everywhere, and one leaky site quietly putting all the others at risk.
OAuth 2.0 arrived in 2012 to solve a related problem. It lets one app use your data on another service without you handing over your password. Picture a photo printing site that wants to pull pictures from your Google Photos. Instead of giving it your Google password, you let Google hand it a limited key that only opens your photos. OAuth answers one question: what is this app allowed to do?
Then websites had a bright idea. If Google already knows who you are, why not let Google sign you in too? So they started using OAuth for login. The catch was that OAuth was never designed to say who the user is. Every provider bolted identity on in its own way, and some of those setups could be tricked into signing in the wrong person. Not a great quality in a login system.
OpenID Connect (OIDC) came along in 2014 to fix that. It sits on top of OAuth and adds one key thing: an ID token, a digitally signed message from the provider. The ID token says who the user is, who vouched for them, and which app the message is meant for. OIDC answers the other question: who is this user?
Short version: OAuth is about permission, OIDC is about identity. The “Sign in with Google” button you’ve clicked a hundred times uses both.
how a sign-in actually works
When you click “Sign in with…” on a website, here’s roughly what happens behind the scenes:
- The website sends you to the login provider. Your browser lands on the provider’s sign-in page. The website never sees your password, which is the whole point.
- You sign in with the provider. Password, fingerprint, the code from your phone, whatever it asks for.
- The provider sends you back with a one-time code. Your browser returns to the website with the code tacked onto the web address, something like
https://shop.example/callback?code=4f9a2c… - The website swaps the code for tokens. Behind the scenes, the website’s server sends the code straight to the provider. It gets back the ID token, and often an access token too.
- The website checks the ID token and signs you in. Welcome back.
The whole thing takes a second or two, and most people never notice it happening.
the weak spot
Look closely at step 3. The one-time code travels through your browser, right there in the address bar. And address bars are chatty. The code can end up in places it shouldn’t:
- your browser history
- server logs
- on phones, another installed app that’s listening for the same link
That last one isn’t hypothetical. In 2019, researchers at Trend Micro showed how it plays out on iPhones. Apps can claim a custom link format like wechat://, and nothing stops two apps from claiming the same one. A fake app could send WeChat the exact login request that the shopping app Suning sends. WeChat didn’t check who was asking, so it handed the login token straight to the fake app, which could then get into the victim’s Suning account. The researchers also spotted apps in the wild claiming links like wechat://, line:// and fb://.
If someone else gets hold of that code, they may be able to complete step 4 themselves and finish your sign-in.
Some apps have a secret of their own, known only to the app’s server, which they must present at step 4. That helps, but as we’ll see, it doesn’t close the gap completely. Booking.com found this out the hard way, when researchers at Salt Labs took over accounts through its “Log in with Facebook” sign-in, secret and all.
So the question becomes: how does the provider know that whoever brings the code back in step 4 is the same app that started the sign-in in step 1?
That’s exactly the problem PKCE solves.
so what is PKCE?
PKCE stands for Proof Key for Code Exchange, and it’s pronounced “pixy”. (Yes, really. Somebody in the standards world had a sense of humour.) It’s a small add-on to OAuth, published in 2015. It was first designed for phone apps, which can’t keep a secret, but today it’s recommended for every app.
The whole idea fits in one sentence:
At the start of the sign-in, the app makes up a secret and shows the provider only a scrambled version of it. At the end, the app has to show the real secret. Only the app that started the sign-in can finish it.
That’s the trick. Everything else is detail.
a quick word on “scrambled”
PKCE scrambles the secret with a hash, specifically one called SHA-256. A hash is a one-way calculation:
- the same input always gives the same output
- you can’t work backwards from the output to the original input
Think of a smoothie. Turning strawberries into a smoothie takes seconds. Turning a smoothie back into strawberries is not happening. That one-way property is what makes PKCE work.
the sign-in flow, now with PKCE
Here’s the same flow from earlier, now with PKCE in it:
- Before anything else, the app makes a secret. It’s a long random string called the code verifier, and the app keeps it to itself.
- The app hashes the verifier and sends you to the provider. The result of the hash is called the code challenge. The app sends you to the login provider with the challenge attached, plus a note saying which method it used (
S256, meaning SHA-256). The provider saves the challenge for later. - You sign in with the provider. Same as before.
- The provider sends you back with the one-time code. Only the code comes back. The challenge stays with the provider.
- The app swaps the code for tokens, and this time it brings the verifier. The provider hashes the verifier itself and compares the result with the challenge it saved in step 2.
- They match: the provider knows this is the same app that started the sign-in, and hands over the tokens.
- They don’t match: the provider refuses. No tokens, no sign-in.
If you’re curious what these look like, here’s the example pair from the PKCE spec itself:
code verifier: dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
code challenge: E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM # SHA-256, then base64url-encoded
Nothing about the second line gives away the first.
why a stolen code is now useless
Let’s go back to our snoop. Suppose someone manages to see everything that passed through the browser’s address bar. Here’s what they’ve got:
| What they can see | Does it help them? |
|---|---|
| The one-time code | Not without the verifier |
| The challenge (it was in the address at step 2) | No. You can’t work backwards from a hash to the verifier |
| The verifier | Never in the address bar, so they never see it |
The code alone is no longer enough. To use it, you need the verifier, and the verifier never left the app that created it. Our snoop is holding a code and has nothing to do with it.
One rule: always use S256. PKCE also has a method called plain, where the “challenge” is just the verifier itself, unscrambled. That puts the secret straight into the address bar at step 2, and anyone who can read that address now has everything they need. It defeats the whole point.
but what if your app already has a secret?
This was my original question. Some apps run on a server and have their own secret, which they must present when swapping the code. A thief can’t use a stolen code directly without that secret. So is PKCE still needed?
Yes. Here’s the attack the app’s secret doesn’t stop:
- An attacker steals your one-time code.
- The attacker starts their own sign-in on the same website, then stops just before finishing.
- In their own browser, they send your stolen code to the website’s return address.
- The website’s server swaps the code using its own secret. The secret is correct, so that check passes.
- Without further checks, the website could end up signing the attacker in as you.
Sneaky, right? The website’s secret was never the problem, because the website itself is the one presenting it. What’s missing is a link between the code and the sign-in that’s finishing.
PKCE provides that link. In step 4, the website sends the verifier that belongs to the attacker’s sign-in. The provider hashes it and compares the result with the challenge from your sign-in. They don’t match, and the swap is refused before a single token is issued.
OIDC does have its own check for this, called the nonce. But the nonce is checked by the website after the tokens arrive, and only if the website remembers to check it. PKCE is checked by the provider, before anything is handed out. That’s why the current OAuth security guidance, RFC 9700 from January 2025, recommends PKCE even for apps with a secret. Plenty of apps use both, and there’s no harm in wearing a belt and braces.