Sessions and redirects

The client needs storage for the exchange and a way to redirect the browser. Supply per-request session data or use a framework adapter.

Starting a native session

Runtime integrations use an opaque random 256-bit session ID in an HTTP-only, SameSite=Lax cookie. Cookies are Secure by default. Set secure_cookie=False only for local HTTP. The browser must retain its cookie while visiting the provider, and all application instances must share a persistent store.

class SessionStore(Protocol):
    def load(self, id: str) -> dict | None: ...
    def save(self, id: str, data: dict, expires_at: float) -> None: ...

options = SessionOptions(store, cookie_name='authwave.sid', secure_cookie=True,
                         ttl_seconds=86400)

Import store types from authwave.runtime. Expiration is a Unix timestamp in seconds. MemorySessionStore is suitable for local development and loses data on restart.

Store only JSON-compatible records and enforce expiration. Session records include token secrets; keep them on the server. Use store-level concurrency control to serialize mutations to the same session when multiple requests overlap.

Supplying a container

session = GlobalSessionContainer(request_session)
auth = Authenticator(client_key, request_path, session=session)

The container supports get, set, contains, remove with string keys. It does not start a session or discover a process-global visitor. Missing storage raises SessionNotStartedException.

Authentication uses SessionData.STORE_KEY, whose value is Authwave\SessionData. JSON storage is rehydrated into token and response objects. Preserve unrelated application session values.

Redirect behaviour

RedirectHandler.redirect(uri, code=303) raises RedirectSignal. The framework adapter catches this control flow, saves the session and sends the redirect. This can happen during construction as well as login and logout.

Custom redirect handlers implement redirect(uri, code=303). They should transfer control out of the request; tests may record destinations and return normally.

Adapters persist changes even when callbacks fail, set Cache-Control: no-store and buffer results until persistence succeeds. Store failures prevent successful redirects. Streaming responses are outside the buffered adapter contract.

Building a login URI directly

get_login_uri(token) builds a URI without storing the token or redirecting. Prefer the normal login method, which saves the matching token for the provider's return request.

---

Next, see Development and testing.