Package com.tnsai.mcp.auth

Class PkceFlow

java.lang.Object

com.tnsai.mcp.auth.PkceFlow

public class PkceFlow
extends Object

PKCE (Proof Key for Code Exchange) flow implementation with S256 challenge.

Implements the PKCE extension to the OAuth 2.0 Authorization Code flow as defined in RFC 7636. Uses the S256 challenge method for security.

PKCE flow:

1. Generate a random code_verifier (32 bytes, Base64URL-encoded)
2. Compute code_challenge = Base64URL(SHA-256(code_verifier))
3. Include code_challenge and code_challenge_method in authorization request
4. Include code_verifier in token exchange request

Usage:

 PkceChallenge challenge = PkceFlow.generateChallenge();
 String authUrl = PkceFlow.buildAuthorizationUrl(
     "https://auth.example.com/authorize",
     "my-client-id",
     "http://localhost:8080/callback",
     "openid profile",
     "random-state",
     challenge
 );
 // ... user authorizes, callback receives code ...
 TokenResponse token = PkceFlow.exchangeCode(
     "https://auth.example.com/token",
     "my-client-id",
     authCode,
     "http://localhost:8080/callback",
     challenge.codeVerifier()
 );
 

See Also:

• RFC 7636 - PKCE

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	PkceFlow.PkceChallenge	A PKCE challenge pair consisting of verifier, challenge, and method.
static final record	PkceFlow.TokenResponse	Token response from the authorization server.

Constructor Summary

Constructors

Constructor	Description
PkceFlow()

Method Summary

Modifier and Type	Method	Description
static String	buildAuthorizationUrl(String authorizationEndpoint, String clientId, String redirectUri, String scope, String state, PkceFlow.PkceChallenge challenge)	Builds an OAuth authorization URL with PKCE parameters.
static PkceFlow.TokenResponse	exchangeCode(String tokenEndpoint, String clientId, String code, String redirectUri, String codeVerifier)	Exchanges an authorization code for tokens using the PKCE code verifier.
static PkceFlow.PkceChallenge	generateChallenge()	Generates a new PKCE challenge using the S256 method.
static PkceFlow.TokenResponse	refreshToken(String tokenEndpoint, String clientId, String refreshToken)	Refreshes an access token using a refresh token.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

PkceFlow

public PkceFlow()

Method Details

generateChallenge

public static PkceFlow.PkceChallenge generateChallenge()

Generates a new PKCE challenge using the S256 method.

Creates a cryptographically secure random code verifier and computes its SHA-256 hash as the code challenge.

Returns:

a new PKCE challenge pair

buildAuthorizationUrl

public static String buildAuthorizationUrl(String authorizationEndpoint,
 String clientId,
 String redirectUri,
 String scope,
 String state,
 PkceFlow.PkceChallenge challenge)

Builds an OAuth authorization URL with PKCE parameters.

Parameters:

authorizationEndpoint - the authorization endpoint URL

clientId - the client ID

redirectUri - the redirect URI for the callback

scope - the requested scope

state - the state parameter for CSRF protection

challenge - the PKCE challenge

Returns:

the complete authorization URL

exchangeCode

public static PkceFlow.TokenResponse exchangeCode(String tokenEndpoint,
 String clientId,
 String code,
 String redirectUri,
 String codeVerifier)
                                           throws IOException

Exchanges an authorization code for tokens using the PKCE code verifier.

Parameters:

tokenEndpoint - the token endpoint URL

clientId - the client ID

code - the authorization code received from the callback

redirectUri - the redirect URI used in the authorization request

codeVerifier - the PKCE code verifier

Returns:

the token response

Throws:

IOException - if the token exchange request fails

refreshToken

public static PkceFlow.TokenResponse refreshToken(String tokenEndpoint,
 String clientId,
 String refreshToken)
                                           throws IOException

Refreshes an access token using a refresh token.

Parameters:

tokenEndpoint - the token endpoint URL

clientId - the client ID

refreshToken - the refresh token

Returns:

the new token response

Throws:

IOException - if the refresh request fails