Package com.broadleafcommerce.auth.authorization.security.tokenblacklist

Interface TokenBlacklistManager

All Known Implementing Classes:
LocalMemoryTokenBlacklistManager, RedisTokenBlacklistManager
public interface TokenBlacklistManager

A general purpose interface representing the central component responsible for token blacklisting in security flows. This is primarily relevant for Broadleaf session tokens. For OAuth2 access tokens and refresh tokens, the OAuth2 Token Revocation Endpoint is used instead.

Token blacklisting is a security mechanism helpful in stateless, token-based authentication architectures. In a standard stateless OAuth2 or JWT-based setup, authentication session tokens are self-contained, cryptographically signed JWT objects. Because verification is typically performed statelessly by validating the signature and checking expiration claims, a token remains valid until its configured expiration time (TTL) has elapsed, even if the user explicitly performs a logout. Generally, this is not a significant risk because the StatelessUtil.getSessionCookie(OAuth2SessionToken) is marked as HTTP-only and Secure, making it hard to steal such a token in the first place. Furthermore, logout will always remove the session cookie from the client application, ensuring the token is deleted client-side. Nonetheless, to enhance the security of the application, token blacklisting ensures there is a server-side mechanism invalidating the use of session tokens after the user has logged out.

Rather than tracking and blacklisting individual raw session token values on every routine sliding-window refresh (which can cause performance overhead and concurrency issues for concurrent client requests), the framework employs a SessionTokenClaimKeys.SESSION_ID lineage approach. When blacklisting occurs (e.g. during logout or re-login), the unique SessionTokenClaimKeys.SESSION_ID is blacklisted. All session tokens sharing that SessionTokenClaimKeys.SESSION_ID are immediately invalidated, eliminating the need to write to the blacklist on every single token refresh.

This manager provides the core interface for maintaining a registry of revoked or invalidated tokens (typically backed by a high-performance cache or store, such as Redis) during their remaining validity period.

Overall Integration Flow

When a user signs out, AuthenticationLogoutHandler ensures their active session token's SessionTokenClaimKeys.SESSION_ID is registered in the blacklist with a TTL matching its remaining maximum lifetime. Subsequent requests utilizing any session token sharing this SessionTokenClaimKeys.SESSION_ID are intercepted and rejected by OAuth2SessionAuthenticationProvider.

Similarly, in DefaultSessionAuthenticationStrategy, where a new session token is being issued while an existing valid session token is already present (e.g. on re-authentication), the existing session's SessionTokenClaimKeys.SESSION_ID will be blacklisted to ensure the previous session lineage is completely invalidated.

In some cases, clients may be leveraging the "Remember Me" login functionality. Please note that unlike session tokens, "remember me" tokens are not stateless, and are tracked server-side already. RememberMeLogoutHandlerDelegate invalidates those server-side tokens at logout, eliminating the need for blacklisting there.

Additional note - CSR Impersonation via ImpersonationEndpoint results in a session cookie being issued for the CSR. There is no dedicated 'end impersonation' flow at the time of writing - typically, CSRs end impersonation simply by engaging a standard logout. For this reason, the standard blacklisting flow on logout described above is sufficient to handle this case.

Since:
AuthenticationServices 3.0.0, Release Train 3.0.0

  • Method Details

    • blacklist

      void blacklist(TokenBlacklistRequest request)
      Registers the given token with the token blacklist.
      Parameters:
      request - details about the token to blacklist
      Throws:
      TokenBlacklistOperationException - if an unexpected error occurs during the operation

    • isBlacklisted

      boolean isBlacklisted(TokenBlacklistDetectionRequest request)
      Reports whether the given token is blacklisted.
      Parameters:
      request - details about the token to check the blacklist status of
      Returns:
      true if the token is blacklisted, false otherwise
      Throws:
      TokenBlacklistOperationException - if an unexpected error occurs during the operation