Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Stateless Auth Handler

The stateless-auth module in light-spa-4j provides a robust, stateless authentication mechanism for Single Page Applications (SPAs). It handles the OAuth 2.0 Authorization Code flow and manages the resulting tokens using secure, HTTP-only cookies, eliminating the need for client-side storage (like localStorage).

Core Components

StatelessAuthHandler

This middleware implements the Backend-For-Frontend (BFF) pattern:

  • Authorization: Intercepts requests to /authorization, exchanges the authorization code for access and refresh tokens from the OAuth 2.0 provider.
  • Cookie Management: Stores tokens in secure, HTTP-only cookies (accessToken, refreshToken) and exposes non-sensitive user info (id, roles) in JavaScript-readable cookies.
  • CSRF Protection: Generates and validates Double Submit Cookies (CSRF token in header vs. JWT claim) to prevent Cross-Site Request Forgery.
  • Token Renewal: Automatically renews expiring access tokens using the refresh token when the session is nearing timeout (default check at < 1.5 minutes remaining).
  • Logout: Handles requests to /logout by invalidating all session cookies.

StatelessAuthConfig

Configuration class that loads settings from statelessAuth.yml. Supports hot reloading and module registration.

Configuration

The module is configured via statelessAuth.yml.

Key Settings:

  • enabled: Enable or disable the handler.
  • authPath: Path to handle the authorization code callback (default: /authorization).
  • logoutPath: Path that clears the BFF session (default: /logout).
  • logoutCsrfEnforced: Enforce logout double-submit CSRF after observe-only qualification (default: false).
  • cookieDomain: Domain for the session cookies (e.g., localhost or your domain).
  • cookiePath: Path scope for cookies (default: /).
  • cookieSecure: Set to true for HTTPS environments.
  • sessionTimeout: Expiration time for session cookies.
  • redirectUri: Where to redirect the SPA after successful login.
  • enableHttp2: Whether to use HTTP/2 for backend token calls.

Social Login Support: The configuration also includes sections for configuring social login providers directly if not federating through a central IdP:

  • googlePath, googleClientId, googleRedirectUri
  • facebookPath, facebookClientId
  • githubPath, githubClientId

HTTP Contract

/authorization and enabled /google, /facebook, and /github endpoints are OAuth authorization-code callbacks and remain GET-only. They accept code and optional state query parameters and are not part of the mutation method migration.

Logout is a credentialed, bodyless POST to /logout with X-CSRF-TOKEN read from the readable csrf cookie. A zero-length request is valid even when a shared client declares Content-Type: application/json. Successful logout returns 204 No Content, no response content type or body, and deletion cookies for every cookie name the handler can set. Route OPTIONS /logout explicitly through a chain with CORS before stateless.

Logout is POST-only. A legacy GET or another unsupported method returns HTTP 405, ERR10008, and Allow: POST before cookie deletion.