com.aspc.cms.rest.plugin.oidc

Class OidcCookieUtil

java.lang.Object

com.aspc.cms.rest.plugin.oidc.OidcCookieUtil

public final class OidcCookieUtil
extends java.lang.Object

Utility class for managing the OIDC refresh token cookie with correct security attributes.

Only the refresh token is stored in an HttpOnly cookie. Access and ID tokens are returned to the frontend in the response body.

Cookie attributes:

• HttpOnly: true — prevents JavaScript access
• Secure: true — HTTPS only (required with SameSite=None)
• SameSite: None on HTTPS — allow credentialed cross-site calls (via HttpClient.putCookie(Cookie, CookieSameSite))
• Path: / — forced by HttpClient.putCookie(Cookie, CookieSameSite)
• Max-Age — set to the refresh token lifetime

Author:

Claude

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	COOKIE_PATH Cookie path constant for tests/docs.
static java.lang.String	COOKIE_REFRESH_TOKEN The cookie name used to store the refresh token.
static int	DEFAULT_REFRESH_TOKEN_MAX_AGE Default refresh token lifetime: 30 days in seconds.

Method Summary

Modifier and Type	Method and Description
static java.lang.String	buildSameSiteCookieHeader(java.lang.String refreshToken, boolean secure, int maxAgeSeconds) Builds the Set-Cookie header value for the refresh token cookie (test / documentation helper).
static java.lang.String	buildSameSiteCookieHeader(java.lang.String cookieName, java.lang.String cookieValue, boolean secure, int maxAgeSeconds) Builds a complete Set-Cookie header for any OIDC cookie name.
static void	clearRefreshTokenCookie(WebClient client) Clears the refresh token cookie by setting its max-age to zero.
static void	clearSessionTokenCookie(WebClient client) Clears the one-time session key cookie set by GET /oidc/callback.
static java.lang.String	getRefreshTokenCookie(WebClient client) Reads the refresh token from the request cookie.
static void	setRefreshTokenCookie(WebClient client, OidcTokenResponse tokenResponse, RestDefinition restDefinition) Sets the refresh-token cookie using OidcConfig.getRefreshCookieMaxAgeResolver().
static void	setRefreshTokenCookie(WebClient client, java.lang.String refreshToken) Sets a secure, HttpOnly cookie containing the refresh token.
static void	setRefreshTokenCookie(WebClient client, java.lang.String refreshToken, int maxAgeSeconds) Sets a secure, HttpOnly cookie containing the refresh token with a specified max-age.
static void	setSessionTokenCookie(WebClient client, java.lang.String sessionKey, int maxAgeSeconds) Sets the short-lived one-time session token cookie used by GET /oidc/callback.

Methods inherited from class java.lang.Object

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

Field Detail

COOKIE_REFRESH_TOKEN

public static final java.lang.String COOKIE_REFRESH_TOKEN

The cookie name used to store the refresh token.

See Also:

Constant Field Values

COOKIE_PATH

public static final java.lang.String COOKIE_PATH

Cookie path constant for tests/docs. Runtime path is forced to / by HttpClient.putCookie(Cookie, CookieSameSite).

See Also:

Constant Field Values

DEFAULT_REFRESH_TOKEN_MAX_AGE

public static final int DEFAULT_REFRESH_TOKEN_MAX_AGE

Default refresh token lifetime: 30 days in seconds.

See Also:

Constant Field Values

Method Detail

setRefreshTokenCookie

public static void setRefreshTokenCookie(@Nonnull
                                         WebClient client,
                                         @Nonnull
                                         java.lang.String refreshToken)

Sets a secure, HttpOnly cookie containing the refresh token.

Parameters:

client - the WebClient for the current request

refreshToken - the refresh token value to store

setRefreshTokenCookie

public static void setRefreshTokenCookie(@Nonnull
                                         WebClient client,
                                         @Nonnull
                                         java.lang.String refreshToken,
                                         int maxAgeSeconds)

Sets a secure, HttpOnly cookie containing the refresh token with a specified max-age.

Parameters:

client - the WebClient for the current request

refreshToken - the refresh token value to store

maxAgeSeconds - the cookie lifetime in seconds

setRefreshTokenCookie

public static void setRefreshTokenCookie(@Nonnull
                                         WebClient client,
                                         @Nonnull
                                         OidcTokenResponse tokenResponse,
                                         @Nonnull
                                         RestDefinition restDefinition)

Sets the refresh-token cookie using OidcConfig.getRefreshCookieMaxAgeResolver().

Parameters:

client - the WebClient for the current request

tokenResponse - Cognito token response (must include a refresh token)

restDefinition - the REST route handling this login or refresh

setSessionTokenCookie

public static void setSessionTokenCookie(@Nonnull
                                         WebClient client,
                                         @Nonnull
                                         java.lang.String sessionKey,
                                         int maxAgeSeconds)

Sets the short-lived one-time session token cookie used by GET /oidc/callback.

Parameters:

client - the WebClient for the current request

sessionKey - the cache key for access/ID tokens

maxAgeSeconds - cookie lifetime in seconds

getRefreshTokenCookie

@CheckReturnValue
 @Nullable
public static java.lang.String getRefreshTokenCookie(@Nonnull
                                                                                  WebClient client)

Reads the refresh token from the request cookie.

Parameters:

client - the WebClient for the current request

Returns:

the refresh token value, or null if the cookie is not present or blank

clearRefreshTokenCookie

public static void clearRefreshTokenCookie(@Nonnull
                                           WebClient client)

Clears the refresh token cookie by setting its max-age to zero.

Used during logout to remove the refresh token from the browser.

Parameters:

client - the WebClient for the current request

clearSessionTokenCookie

public static void clearSessionTokenCookie(@Nonnull
                                           WebClient client)

Clears the one-time session key cookie set by GET /oidc/callback.

Parameters:

client - the WebClient for the current request

buildSameSiteCookieHeader

@CheckReturnValue
 @Nonnull
public static java.lang.String buildSameSiteCookieHeader(@Nonnull
                                                                                     java.lang.String refreshToken,
                                                                                     boolean secure,
                                                                                     int maxAgeSeconds)

Builds the Set-Cookie header value for the refresh token cookie (test / documentation helper). Prefers HttpClient.putCookie(Cookie, CookieSameSite) at runtime.

When secure is true, emits SameSite=None; Secure. Without Secure, browsers reject SameSite=None, so HTTP uses SameSite=Lax.

Parameters:

refreshToken - the refresh token value

secure - whether to include the Secure flag (and SameSite=None)

maxAgeSeconds - the cookie lifetime in seconds

Returns:

the complete Set-Cookie header value

buildSameSiteCookieHeader

@CheckReturnValue
 @Nonnull
public static java.lang.String buildSameSiteCookieHeader(@Nonnull
                                                                                     java.lang.String cookieName,
                                                                                     @Nonnull
                                                                                     java.lang.String cookieValue,
                                                                                     boolean secure,
                                                                                     int maxAgeSeconds)

Builds a complete Set-Cookie header for any OIDC cookie name.

Parameters:

cookieName - cookie name

cookieValue - cookie value

secure - whether the request is HTTPS

maxAgeSeconds - cookie lifetime in seconds

Returns:

the complete Set-Cookie header value