PKCE Flow

Proof Key for Code Exchange (PKCE, pronounced "pixie") is an extension to the OAuth 2.0 Authorization Code flow designed to prevent "authorization code injection" attacks.

While originally created for mobile apps, it is now considered a best practice for all OAuth 2.0 clients, especially public clients like Single Page Applications (SPAs) and mobile/desktop applications that cannot safely store a client secret.

Why PKCE?

In a standard Authorization Code flow, a client swaps an authorization code for an access token. If an attacker intercepts this code, they could potentially exchange it for a token themselves. PKCE solves this by ensuring that the party requesting the token is the same party that initiated the authorization request, without requiring a client secret.

Automatic Handling

The good news is that authkestra handles PKCE automatically when you use the OAuth2Flow.

When a flow is initiated, authkestra generates the necessary cryptographic keys, includes the challenge in the authorization URL, and verifies the verifier during the token exchange. You don't need to manually manage these secrets or handle the hashing logic.

How it Works

PKCE introduces two key components:

1. Code Verifier: A high-entropy cryptographic random string generated by the client.
2. Code Challenge: A transformed version of the code verifier (usually using SHA-256 hashing) that is sent to the authorization server.

The Process

1. Initiation: authkestra generates a random code_verifier.
2. Challenge: It then creates a code_challenge by hashing the verifier.
3. Request: The code_challenge is sent to the Authorization Server as part of the initial authorization request.
4. Exchange: When exchanging the authorization code for a token, authkestra sends the original code_verifier.
5. Verification: The Authorization Server hashes the received code_verifier and compares it to the code_challenge it received earlier. If they match, the token is issued.

Usage

For most users, no extra configuration is needed. If you are using the standard authkestra flows (like those provided by authkestra-axum or authkestra-actix), PKCE is enabled by default to ensure maximum security for your users.

Advanced Usage

If you are building custom integration logic and need to work with PKCE parameters manually, you can use the Pkce struct from authkestra_core.

use authkestra_core::pkce::Pkce;

// Generate a new PKCE pair
let pkce = Pkce::new();

// Use these in your custom flow
let verifier = &pkce.code_verifier;
let challenge = &pkce.code_challenge;

Full Examples

Since PKCE is an enhancement of the OAuth2 flow, see the OAuth2 examples for practical integration:

• Axum OAuth2 (PKCE enabled by default)
• Actix-web GitHub Example