Class OidcLoginStateCodec

java.lang.Object
io.fluxzero.idp.client.OidcLoginStateCodec
public class OidcLoginStateCodec extends Object
Encodes OidcLoginState into an encrypted, authenticated, cookie-safe value.

BFF applications can store the returned value in a short-lived HttpOnly; SameSite=Lax cookie. Any BFF instance that has the same secret can decrypt and validate the callback, so the login transaction no longer depends on per-instance in-memory state. The payload is encrypted with AES-GCM because it contains the PKCE code verifier.

  • Constructor Details

    • OidcLoginStateCodec

      public OidcLoginStateCodec(String secret)
      Creates a codec from a shared application secret.

      Text secrets must be at least 32 characters and are derived to an AES-256 key using SHA-256. Secrets prefixed with base64: are decoded as raw AES keys and must decode to 16, 24 or 32 bytes.

      Parameters:
      secret - shared secret for all BFF instances that serve the same application

    • OidcLoginStateCodec

      public OidcLoginStateCodec(byte[] keyBytes)
      Creates a codec from a raw AES key.
      Parameters:
      keyBytes - AES key bytes, length 16, 24 or 32

  • Method Details

    • encode

      public String encode(OidcLoginState loginState)
      Encodes a login state into an encrypted cookie value.

    • decode

      public Optional<OidcLoginState> decode(String cookieValue, Instant now)
      Decodes and validates a login state cookie value.

      Invalid, tampered or expired values return Optional.empty().

      Parameters:
      cookieValue - encoded cookie value
      now - current time used for expiry validation
      Returns:
      decoded login state when valid and not expired

    • decodeOrThrow

      public OidcLoginState decodeOrThrow(String cookieValue)
      Decodes a cookie value and throws when it is invalid or tampered.