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 often pronounced/referenced as ‘pixie’.
What is its purpose?
The main purpose of doing this is to protect public clients from having an authorization code intercepted during an authentication exchange.
Client Secret cannot be properly secured in these environments, the public client authenticates using only the
and the PKCE parameters.
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
. This ensures that the client exchanging the
Authorization Code for the
Access Token is the same one that initially requested the
It is 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
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
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.