Proof Key for Code Exchange (PKCE)
What is it?
The Proof Key for Code Exchange (PKCE) extension adds additional security to the OAuth 2.0 Authorization Code flow.
PKCE is typically pronounced the same as the word ‘pixie’.
What is its purpose?
PKCE’s main purpose is to prevent public clients from having an authorization code intercepted during an authentication exchange.
Note: Since public clients have no
client_secret, this parameter should be ommitted from the request parameters for the OAuth flow (even if sent as an blank/empty value).
How do I use it?
The requesting app creates a secret (known as the Code Verifier) and submits a hash of that secret (known as the Code Challenge) on the initial authentication request.
The secret itself (the Code Verifier) is later submitted as part of exchanging the Authorization Code for an Access Token. This ensures that the client exchanging the Authorization Code for the Access Token is the same one that initially requested the Authorization Code.
It can be difficult to generate the correct values for the Code Verifier and Code Challenge from the command line.
It is recommended to use an OAuth client that supports PKCE.
Generating a code verifier
A client needs to generate a random string of characters. The string must be at least 43 bytes long and no more than 128 bytes. It must be composed of only the following characters:
- English letters A-Z or a-z
- Numbers 0-9
- Symbols “-”, “.”, “_” or “~”.
Creating the code challenge
The code challenge is created by generating a SHA-256 byte hash of the code verifier. The result is then base64url-encoded.
Example code verifier and code challenge creation
const crypto = require('crypto'); const codeVerifier = crypto .randomBytes(60) .toString('hex') .slice(0, 128); const codeChallenge = crypto .createHash('sha256') .update(Buffer.from(codeVerifier)) .digest('base64') .replace(/=/g, '') .replace(/\+/g, '-') .replace(/\//g, '_');
To check your work, use this code_verifier and ensure you get the listed code_challenge:
Check your work: Paste in a verifier or hit the create button to generate one.
How have others used it?
The Simple Plugin Example on GitHub uses the Node.js crypto library to handle PKCE support.
The OAuth 2.1 draft specification requires PKCE for all OAuth clients which use the Authorization Code flow.
Our v0 authentication endpoints include support for OAuth 2.1 in anticipation of the draft specification being approved in the near future.
Migration guide for Consumer API
Do you have code that uses our deprecated and unversioned authentication endpoints when authenticating to the Consumer API?
If so, you’ll want to upgrade to use the v0 authentication endpoints.
We recommend reading the Guide on Migrating to the V0 OpenID Connect Endpoints.