litestar-auth-guards

Litestar Auth and Guards

Use this skill for authentication boundaries, authorization checks, guard composition, and user context.

Code Style Rules

• Put auth and permission checks in Guards or middleware, not handler bodies.
• Prefer Controller-level guards when a whole domain shares a policy.
• Raise Litestar HTTP exceptions or domain exceptions consistently.
• Keep tenant isolation explicit in guard logic and service filters.
• Let authentication middleware populate connection.user and connection.auth; use guards for authorization.

Quick Reference

• Guard patterns: guards.md
• Middleware user loading: litestar-middleware
• Realtime auth: litestar-realtime

Workflow

1. Determine where identity is loaded.
2. Add Guards at app, Controller, or route scope.
3. Keep permission checks reusable and testable.
4. Verify denial paths and authenticated success paths.

Guardrails

• Do not inline auth checks in handlers.
• Do not make Guards perform database work repeatedly when middleware can load the user once.
• Do not trust client-supplied tenant IDs without server-side scoping.
• Do not use HTTP-only assumptions for WebSocket auth.
• Do not claim WebSocket handshakes cannot carry headers. Non-browser clients can send them; the browser WebSocket API cannot set arbitrary headers.

Validation Checkpoint

• Guard scope matches the policy scope.
• Denial paths return the expected status.
• Handlers contain no duplicated auth branching.
• Browser WebSocket routes use cookies, a short-lived query token, or a first-message protocol; non-browser header auth is documented separately.

Example

from litestar.connection import ASGIConnection
from litestar.exceptions import PermissionDeniedException
from litestar.handlers import BaseRouteHandler


async def requires_active_user(connection: ASGIConnection, _: BaseRouteHandler) -> None:
    if not connection.user or not connection.user.is_active:
        raise PermissionDeniedException("Authentication required")