Authorization and sessions

Authentication establishes identity; authorization checks whether that identity may perform an operation. A session is the application contract that carries identity information across requests.

Check roles and scopes#

AdminGuard in the authentication example checks for a principal first, then checks has_role("admin"). Use #[guard(AuthGuard, AdminGuard)] on the action to run authentication before authorization.

Principal carries subject, role, scope, and claim data. Do not derive these values from freely supplied client headers without verification. They must come from verified credentials or a server-side session.

Session middleware slot#

session_middleware::<ApplicationSessionMiddleware>() runs your application's session preparation step before global CSRF. At most one session middleware can be registered.

AppBuilder::new("127.0.0.1:8080")
    .session_middleware::<ApplicationSessionMiddleware>();

ApplicationSessionMiddleware is an application-defined type implementing HttpMiddleware; it is not a built-in Lily session store.

Session flow#

1. Read the cookie and validate its format.
2. Load the session from the session store and check expiry/revocation.
3. Publish the verified principal and, if needed, CsrfSessionId.
4. Continue the flow with next.run(exchange).
5. Apply your chosen renewal and response-cookie policy.

Whether a missing or invalid session means anonymous access or rejection depends on the endpoint policy. Keep required identity checks in the action guard.

Store and refresh responsibilities#

Your application owns the storage schema, expiry, revocation, and refresh-token rotation. Redis cache or a database can underlie this store; adding the crate does not automatically enable session management.

Combine with CSRF#

Session middleware can place the verified session ID in the request-local binding. In signed CSRF mode, rotate the token with the new binding when the session ID changes. In synchronizer mode, clear the old binding's token state first, then change the session ID and issue a new token. See CSRF for the complete setup.