# Litestar Authentication

> Implement Litestar authentication with custom authentication middleware, built-in security backends, JWT and session flows, route inclusion and exclusion rules, and typed auth context on `Request` / `ASGIConnection`. Use when establishing identity, issuing or validating credentials, or attaching authenticated user context in Litestar. Do not use for generic request parsing, broad security audits, or unrelated transport concerns.

- Skill: `alti3/litestar-authentication` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add alti3/litestar-authentication`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alti3/litestar-authentication/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: alti3 (https://skillmd.com/u/alti3)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/alti3/litestar-authentication

---


# Authentication

## Execution Workflow

1. Choose the identity mechanism first: session, JWT header, JWT cookie, OAuth2 password bearer, or custom middleware based on client and trust boundaries.
2. Attach authentication once at app scope with `on_app_init` or middleware.
3. Configure exclusion rules explicitly for login, schema, health, and other public routes.
4. Use `request.user` and `request.auth` only after authentication has been established.
5. Apply guards separately for authorization checks.
6. Keep missing or invalid credential behavior consistent with the exception-handling strategy.

## Core Rules

- Keep authentication separate from request parsing and authorization.
- Let request parsing validate input fields before auth-specific business logic where possible.
- Prefer built-in security backends before custom middleware.
- Use custom middleware only when the identity source does not fit a built-in backend.
- Treat `request.user` and `request.auth` as authenticated context, not parsing shortcuts.
- Keep exclusion rules narrow and reviewable.
- Normalize identity failures to `401` behavior unless the project has a documented alternative.

## Decision Guide

- Use `SessionAuth` for browser-first applications with server-managed sessions.
- Use `JWTAuth` for token-in-header API clients.
- Use `JWTCookieAuth` for browser flows where token cookies are intentional.
- Use `OAuth2PasswordBearerAuth` when password-flow token issuance semantics are required.
- Use `AbstractAuthenticationMiddleware` when the credential source or validation logic is custom.
- Use `litestar-security` when the task includes authorization policy, secrets, and defense-in-depth concerns beyond identity wiring.

## Reference Files

Read only the sections you need:

- For custom middleware, built-in backends, request auth context, exclusion rules, and login patterns, read [references/auth-patterns.md](references/auth-patterns.md).

## Recommended Defaults

- Keep authentication middleware or backend registration at app scope.
- Exclude only explicitly public routes.
- Access authenticated context through typed `Request` or `ASGIConnection` after auth runs.
- Keep token issuance and logout flows explicit and testable.
- Hand off `401` / `403` response formatting to `litestar-exception-handling`.

## Anti-Patterns

- Parsing auth headers manually in every route handler.
- Mixing authorization policy into authentication middleware.
- Treating `request.user` as available on routes excluded from authentication.
- Using broad path exclusions that create accidental public surface area.
- Hardcoding secrets or sample tokens outside local examples.

## Validation Checklist

- Confirm protected endpoints reject missing or invalid credentials.
- Confirm public routes are public only when explicitly excluded.
- Confirm `request.user` and `request.auth` have the expected types on authenticated routes.
- Confirm login and logout flows produce the intended token or session behavior.
- Confirm identity failures line up with the exception-handling contract.
- Confirm tests cover both authenticated and unauthenticated paths.

## Cross-Skill Handoffs

- Use `litestar-requests` for header, cookie, and body parsing concerns that are not identity-specific.
- Use `litestar-security` for authorization, secret hygiene, and broader security posture.
- Use `litestar-exception-handling` to standardize `401` and `403` contracts.
- Use `litestar-testing` for auth boundary, exclusion-rule, and token-flow tests.

## Litestar References

- https://docs.litestar.dev/latest/usage/security/abstract-authentication-middleware.html
- https://docs.litestar.dev/latest/usage/security/security-backends.html
- https://docs.litestar.dev/latest/usage/security/jwt.html
- https://docs.litestar.dev/latest/usage/security/excluding-and-including-endpoints.html