com.aspc.cms.rest.plugin.oidc

Class OidcTokenExchange

java.lang.Object

com.aspc.cms.rest.plugin.oidc.OidcTokenExchange

public final class OidcTokenExchange
extends java.lang.Object

Handles server-side HTTP calls to Cognito's /oauth2/token endpoint for exchanging authorisation codes and refreshing tokens.

All methods read configuration from OidcConfig and POST form-encoded requests to the Cognito token endpoint.

Author:

Claude

Field Summary

Fields

Modifier and Type	Field and Description
static int	REFRESH_COOLDOWN_SECONDS Cooldown period in seconds — refresh tokens created within this window cannot be refreshed.

Method Summary

Modifier and Type	Method and Description
static java.lang.String	buildAuthorizationCodeRequestForm(java.lang.String code, java.lang.String redirectUri, java.lang.String codeVerifier) Builds the application/x-www-form-urlencoded body for a Cognito authorization_code token request.
static void	clearAllCooldowns() Clears all cooldown entries.
static void	clearRefreshTokenCooldown(java.lang.String refreshToken) Removes a refresh token from the cooldown cache.
static OidcTokenResponse	exchangeAuthCode(java.lang.String code) Exchanges an authorisation code for tokens using the authorization_code grant type.
static OidcTokenResponse	exchangeAuthCodeWithPkce(java.lang.String code, java.lang.String redirectUri, java.lang.String codeVerifier) Exchanges an authorisation code for tokens using PKCE and an explicit redirect_uri (typically the SPA callback URL registered in Cognito).
static OidcTokenResponse	parseTokenResponse(java.lang.String responseBody) Parses a successful JSON response into an OidcTokenResponse.
static OidcTokenResponse	postTokenRequest(java.lang.String tokenEndpoint, java.lang.String formBody) Posts a form-encoded request to the given token endpoint and parses the JSON response.
static void	recordRefreshTokenCreation(java.lang.String refreshToken) Records that a refresh token has just been created or refreshed.
static OidcTokenResponse	refreshTokens(java.lang.String refreshToken) Exchanges a refresh token for new access and ID tokens using the refresh_token grant type.

Methods inherited from class java.lang.Object

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

Field Detail

REFRESH_COOLDOWN_SECONDS

public static final int REFRESH_COOLDOWN_SECONDS

Cooldown period in seconds — refresh tokens created within this window cannot be refreshed.

See Also:

Constant Field Values

Method Detail

exchangeAuthCode

@CheckReturnValue
 @Nonnull
public static OidcTokenResponse exchangeAuthCode(@Nonnull
                                                                             java.lang.String code)
                                                                      throws OidcTokenExchangeException

Exchanges an authorisation code for tokens using the authorization_code grant type.

Parameters:

code - the authorisation code received from Cognito's callback

Returns:

the token response containing access, ID, and refresh tokens

Throws:

OidcTokenExchangeException - if Cognito returns an error or the request fails

exchangeAuthCodeWithPkce

@CheckReturnValue
 @Nonnull
public static OidcTokenResponse exchangeAuthCodeWithPkce(@Nonnull
                                                                                     java.lang.String code,
                                                                                     @Nonnull
                                                                                     java.lang.String redirectUri,
                                                                                     @Nonnull
                                                                                     java.lang.String codeVerifier)
                                                                              throws OidcTokenExchangeException

Exchanges an authorisation code for tokens using PKCE and an explicit redirect_uri (typically the SPA callback URL registered in Cognito).

Use this for Option A: the browser lands on the SPA with ?code=; the SPA POSTs code, redirect_uri, and code_verifier to the backend.

Parameters:

code - the authorisation code

redirectUri - the exact redirect URI sent to Cognito on authorize

codeVerifier - the PKCE code verifier

Returns:

the token response

Throws:

OidcTokenExchangeException - if Cognito returns an error or the request fails

buildAuthorizationCodeRequestForm

@CheckReturnValue
 @Nonnull
public static java.lang.String buildAuthorizationCodeRequestForm(@Nonnull
                                                                                             java.lang.String code,
                                                                                             @Nonnull
                                                                                             java.lang.String redirectUri,
                                                                                             @Nullable
                                                                                             java.lang.String codeVerifier)

Builds the application/x-www-form-urlencoded body for a Cognito authorization_code token request.

Parameters:

code - authorisation code

redirectUri - redirect URI (must match the authorize request)

codeVerifier - PKCE verifier, or null to omit

Returns:

encoded form body

refreshTokens

@CheckReturnValue
 @Nonnull
public static OidcTokenResponse refreshTokens(@Nonnull
                                                                          java.lang.String refreshToken)
                                                                   throws OidcTokenExchangeException

Exchanges a refresh token for new access and ID tokens using the refresh_token grant type.

Note: Cognito does not return a new refresh token in the response for refresh_token grants.

Parameters:

refreshToken - the refresh token

Returns:

the token response containing new access and ID tokens

Throws:

OidcTokenExchangeException - if Cognito returns an error or the request fails

postTokenRequest

@CheckReturnValue
 @Nonnull
public static OidcTokenResponse postTokenRequest(@Nonnull
                                                                             java.lang.String tokenEndpoint,
                                                                             @Nonnull
                                                                             java.lang.String formBody)
                                                                      throws OidcTokenExchangeException

Posts a form-encoded request to the given token endpoint and parses the JSON response.

Parameters:

tokenEndpoint - the Cognito token endpoint URL

formBody - the URL-encoded form body

Returns:

the parsed token response

Throws:

OidcTokenExchangeException - on HTTP or parsing errors

parseTokenResponse

@CheckReturnValue
 @Nonnull
public static OidcTokenResponse parseTokenResponse(@Nonnull
                                                                               java.lang.String responseBody)
                                                                        throws OidcTokenExchangeException

Parses a successful JSON response into an OidcTokenResponse.

Throws:

OidcTokenExchangeException

recordRefreshTokenCreation

public static void recordRefreshTokenCreation(@Nonnull
                                              java.lang.String refreshToken)

Records that a refresh token has just been created or refreshed. Subsequent calls to refreshTokens(java.lang.String) within the cooldown period will be rejected with a too_many_requests error.

Parameters:

refreshToken - the refresh token to record

clearRefreshTokenCooldown

public static void clearRefreshTokenCooldown(@Nonnull
                                             java.lang.String refreshToken)

Removes a refresh token from the cooldown cache.

Parameters:

refreshToken - the refresh token to remove

clearAllCooldowns

public static void clearAllCooldowns()

Clears all cooldown entries. Intended for testing only.