Jonas Notes

PKCE

3 min read

Deep Dive into PKCE (Proof Key for Code Exchange)

Introduction to PKCE

PKCE (Proof Key for Code Exchange) is an extension to the OAuth 2.0 authorization code flow to mitigate authorization code interception attacks. Originally developed for mobile and single-page applications (SPAs), PKCE enhances security by adding an additional layer of protection during the OAuth flow.

Key Concepts

  1. Authorization Code Interception:

    • In traditional OAuth 2.0, if an attacker intercepts the authorization code, they can exchange it for an access token. PKCE prevents this by using dynamically generated secrets.

  2. Code Verifier:

    • A high-entropy cryptographic random string used to create a code challenge.

  3. Code Challenge:

    • Derived from the code verifier using a transformation method (usually SHA-256). The code challenge is sent with the authorization request.

  4. Code Challenge Method:

    • Specifies the transformation method used to generate the code challenge from the code verifier. Common methods are plain (no transformation) and S256 (SHA-256).

PKCE Flow Steps

  1. Client Generates Code Verifier and Code Challenge:

    • The client generates a random code verifier.
    • The client creates a code challenge by applying a transformation (usually SHA-256) to the code verifier.

  2. Authorization Request:

    • The client initiates the authorization request, including the code challenge and code challenge method.

  3. User Authentication and Authorization:

    • The user authenticates and grants permission to the client application.

  4. Authorization Code:

    • The authorization server issues an authorization code and includes the original code challenge.

  5. Token Request:

    • The client exchanges the authorization code for an access token, including the original code verifier.

  6. Token Issuance:

    • The authorization server validates the code verifier against the stored code challenge. If valid, it issues the access token.

Example Implementation

  1. Generate Code Verifier and Code Challenge:
const crypto = require('crypto');
 
function base64URLEncode(str) {
  return str.toString('base64')
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=/g, '');
}
 
function sha256(buffer) {
  return crypto.createHash('sha256').update(buffer).digest();
}
 
const codeVerifier = base64URLEncode(crypto.randomBytes(32));
const codeChallenge = base64URLEncode(sha256(codeVerifier));
 
console.log('Code Verifier:', codeVerifier);
console.log('Code Challenge:', codeChallenge);
  1. Authorization Request:
GET /authorize?
response_type=code&
client_id=YOUR_CLIENT_ID&
redirect_uri=https://your-app.com/callback&
code_challenge=CODE_CHALLENGE&
code_challenge_method=S256 HTTP/1.1
Host: authorization-server.com
  1. Token Request:
POST /token HTTP/1.1
Host: authorization-server.com
Content-Type: application/x-www-form-urlencoded
 
grant_type=authorization_code&
code=AUTH_CODE&
redirect_uri=https://your-app.com/callback&
client_id=YOUR_CLIENT_ID&
code_verifier=CODE_VERIFIER
  1. Authorization Server Validation:
    • The authorization server validates the code_verifier against the stored code_challenge using the specified method (S256 in this case). If they match, the server issues an access token.

Full PKCE Flow Illustrated

  1. Client Registration:

    • The client registers with the authorization server and obtains a client ID.

  2. Generate Code Verifier and Code Challenge:

    • The client generates a code verifier and a corresponding code challenge.
    • Example: 
      Code Verifier: GJj5WlF6Xla8NwSjbZtG7h9Xjd9B1Wx02sM5FsTY2jE
Code Challenge: GLB_eHZxLJMTaM6EYy6SoA5d2t-k_2J5LZ3ojQhODn4

  3. Authorization Request:

    • The client directs the user to the authorization server with the code challenge and code challenge method.
    • Example Request: 
      GET /authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https://your-app.com/callback&code_challenge=GLB_eHZxLJMTaM6EYy6SoA5d2t-k_2J5LZ3ojQhODn4&code_challenge_method=S256 HTTP/1.1
Host: authorization-server.com

  4. User Authentication and Authorization:

    • The user logs in and grants permission to the client application.

  5. Authorization Code Issued:

    • The authorization server redirects the user back to the client with an authorization code.
    • Example Redirect: 
      https://your-app.com/callback?code=AUTH_CODE&state=xyz

  6. Token Request:

    • The client exchanges the authorization code for an access token, including the original code verifier.
    • Example Request: 
      POST /token HTTP/1.1
Host: authorization-server.com
Content-Type: application/x-www-form-urlencoded
 
grant_type=authorization_code&code=AUTH_CODE&redirect_uri=https://your-app.com/callback&client_id=YOUR_CLIENT_ID&code_verifier=GJj5WlF6Xla8NwSjbZtG7h9Xjd9B1Wx02sM5FsTY2jE

  7. Token Issuance:

    • The authorization server validates the code verifier against the stored code challenge. If valid, it issues the access token.

Summary

PKCE is a crucial enhancement to the OAuth 2.0 authorization code flow, particularly for public clients such as mobile and single-page applications. By introducing the code verifier and code challenge, PKCE prevents authorization code interception attacks, ensuring a more secure OAuth flow. Understanding and implementing PKCE is essential for developers looking to build secure, scalable, and robust authentication systems.

Backlinks