PKCE, DPoP and certificate-bound tokens

An OAuth access token is a bearer secret, so a copy from a log, a proxy or a crash report works for anyone until it expires, often an hour. The authorization code that comes before it crosses the browser in an address, where other software on the device may read it. This lesson is about three ways to make a copy useless on its own.

PKCE ties an authorization code to a secret that only the app that started the login holds. DPoP ties an access token to a key pair, with a fresh signed proof for every request. Certificate-bound tokens, which use mutual TLS, tie an access token to the client’s TLS certificate. Each runs here against the examples printed in RFC 7636, RFC 9449 and RFC 8705.

PKCE: a stolen code works only for the app that holds the verifier

In the authorization code flow the person signs in at the authorization server, and the browser carries a short-lived code back to the app. Whoever holds the code can ask the token endpoint for tokens. PKCE, short for proof key for code exchange and defined in RFC 7636, closes that gap. Before the request, the app draws a random code verifierThe random secret that an app draws for one login in PKCE and keeps to itself until it asks for tokens., 32 random bytes written as 43 characters. It sends only the SHA-256 hash of the verifier, the code challenge, with the authorization request, and it sends the verifier itself later, with the code, to the token endpoint. The server hashes the verifier it receives and compares the result with the challenge it stored. RFC 9700, the best current practice for OAuth, requires PKCE for public clients and recommends it for confidential ones. Step through one login:

The program uses the example of RFC 7636 Appendix B. Its 32 bytes become a 43-character verifier, and the SHA-256 hash of that text is the challenge the RFC prints:

// PKCE with the example of RFC 7636, Appendix B: 32 random bytes become the code verifier, and the SHA-256 hash of the
// verifier, written in Base64url, is the code challenge. The challenge travels in the authorization request; the
// verifier only goes to the token endpoint, with the code.
import { createHash } from 'node:crypto';

// The RFC's 32 bytes. A real client draws them from the CSPRNG for every login (crypto.randomBytes(32)).
const bytes = Buffer.from([116, 24, 223, 180, 151, 153, 224, 37, 79, 250, 96, 125, 216, 173, 187, 186, 22, 212, 37, 77, 105, 214, 191, 240, 91, 88, 5, 88, 83, 132, 141, 121]);
const verifier = bytes.toString('base64url');
const challenge = (v) => createHash('sha256').update(v, 'ascii').digest('base64url');
const published = 'E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM';

console.log(`random bytes    ${bytes.length}`);
console.log(`code_verifier   ${verifier}  (${verifier.length} characters)`);
console.log(`code_challenge  ${challenge(verifier)}  (${challenge(verifier).length} characters)`);
console.log(`the RFC's value ${published}  same: ${challenge(verifier) === published}`);
console.log(`syntax of RFC 7636 section 4.1 (43 to 128 of A-Z a-z 0-9 - . _ ~): ${/^[A-Za-z0-9\-._~]{43,128}$/.test(verifier)}`);
console.log('');

// The token endpoint stored the challenge with the code. A copy of the code is no use without the verifier.
const stored = challenge(verifier);
const accepts = (candidate) => challenge(candidate) === stored;
console.log(`token request with the client's verifier       ${accepts(verifier) ? 'tokens issued' : 'invalid_grant'}`);
console.log(`token request with the code and no verifier    ${accepts('') ? 'tokens issued' : 'invalid_grant'}`);
console.log(`token request with the challenge as verifier   ${accepts(stored) ? 'tokens issued' : 'invalid_grant'}`);

random bytes    32
code_verifier   dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk  (43 characters)
code_challenge  E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM  (43 characters)
the RFC's value E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM  same: true
syntax of RFC 7636 section 4.1 (43 to 128 of A-Z a-z 0-9 - . _ ~): true

token request with the client's verifier       tokens issued
token request with the code and no verifier    invalid_grant
token request with the challenge as verifier   invalid_grant

Both values match the RFC. The challenge is one-way, so the authorization request, which another app may read, carries something that cannot be turned back into the verifier. A token request with the copied code and no verifier, or with the challenge in place of the verifier, was refused. PKCE protects the code. DPoP and certificate-bound tokens protect the access token that the code is exchanged for. A token bound with DPoP works only with a signature, made for each request, by the key it was issued to. A token bound to a certificate works only on a mutual TLS connection, where the client presents that certificate during the handshake as well as the server.

PKCE on the server: what to enforce, and the downgrade it must refuse Pro: opens with a Pro, Premium or Ultimate pass