PKCE Overview

What is PKCE?¶

Proof Key for Code Exchange (abbreviated PKCE, pronounced “pixie”) is an extension to the authorization code flow.

Prevents CSRF and authorization code injection attacks using the following technique:

1. Client first creates a secret on each authorization request
2. Uses the same secret again when exchanging the authorization code for an access token.

If the code was intercepted, it will not be useful since the token request relies on the initial secret.

Authorization Request¶

When the native app begins the authorization request, instead of immediately launching a browser, the client first creates what is known as a “code verifier“.

Once the app has generated the code verifier, it uses that to derive the code challenge.

Now that the client has a code challenge string, it includes that and a parameter that indicates which method was used to generate the challenge (plain or S256) along with the standard parameters of the authorization request.

A complete authorization request will have the following parameters:

• response_type=code – indicates that your server expects to receive an authorization code
• client_id= – The client ID you received when you first created the application
• redirect_uri= – Indicates the URL to return the user to after authorization is complete, such as org.example.app://redirect
• state=1234zyx – A random string generated by your application, which you’ll verify later
• code_challenge=XXXXXXXXX – The code challenge generated as previously described
• code_challenge_method=S256 – either plain or S256, depending on whether the challenge is the plain verifier string or the SHA256 hash of the string.

The authorization server should recognize the code_challenge parameter in the request, and associate that with the authorization code it generates.

The server returns the authorization code as normal, and does not include the challenge in the data returned.

Authorization Code Exchange¶

The application will then exchange the authorization code for an access token.

In addition to the parameters defined in Authorization Code Request, the client will also send the code_verifier parameter. A complete access token request will include the following parameters:

• grant_type=authorization_code – Indicates the grant type of this token request
• code – The client will send the authorization code it obtained in the redirect
• redirect_uri – The redirect URL that was used in the initial authorization request
• client_id – The application’s registered client ID
• client_secret (optional) – The application’s registered client secret if it was issued a secret
• code_verifier – The code verifier for the PKCE request, that the app originally generated before the authorization request.

Since the code_challenge and code_challenge_method were associated with the authorization code initially, the server should already know which method to use to verify the code_verifier.

If the method is plain, then the authorization server needs only to check that the provided code_verifier matches the expected code_challenge string. If the method is S256, then the authorization server should take the provided code_verifier and transform it using the same hash method, then comparing it to the stored code_challenge string.

If the verifier matches the expected value, then the server can continue on as normal, issuing an access token and responding appropriately. If there is a problem, then the server responds with an invalid_grant error.

The PKCE extension does not add any new responses, so clients can always use the PKCE extension even if an authorization server does not support it.

Additional Resources:¶

• okta PKCE