litestar-auth¶

Authentication and authorization for Litestar applications: registration, login, email verification, password reset, OAuth2, TOTP (2FA), guards, and optional rate limiting. Everything is wired as a native plugin with transport + strategy composition.

Who it is for¶

Teams building on Litestar who need registration, login, verification, password reset, OAuth, optional 2FA, and route guards without re-implementing security-sensitive flows from scratch.

Features¶

• Plugin entry point — LitestarAuth registers middleware, DI, controllers, and exception handling from one config object.
• Backends — AuthenticationBackend combines a transport (Bearer or Cookie) with a strategy (JWT, database, or Redis tokens).
• User manager — BaseUserManager centralizes password hashing, tokens, hooks, and session invalidation.
• Role contract — bundled and custom SQLAlchemy model families now persist roles through dedicated role / user_role tables, while built-in responses and guards still expose one normalized flat roles collection.
• Role administration — when the plugin has session_maker plus a relational role-capable SQLAlchemy user_model, it registers litestar roles for operator workflows, and apps can opt into litestar_auth.contrib.role_admin for an HTTP admin controller with the same flat user.roles boundary.
• User DTOs — the built-in register/verify/reset/users responses expose normalized roles; self-service updates keep those fields privileged by default.
• Guards — is_authenticated, is_active, is_verified, is_superuser, plus has_any_role(...) / has_all_roles(...) for route-level authorization over flat normalized roles.
• Optional — TOTP, OAuth login and account linking, auth endpoint rate limits.

Documentation map¶

Quick peek¶

"""Home-page quick peek: plugin wiring. Included via pymdownx.snippets."""

from __future__ import annotations

import os
from uuid import UUID

from litestar import Litestar
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker

from litestar_auth import (
    BaseUserManager,
    DatabaseTokenAuthConfig,
    LitestarAuth,
    LitestarAuthConfig,
    UserManagerSecurity,
)
from litestar_auth.models import User

DATABASE_TOKEN_HASH_SECRET = os.environ["LITESTAR_AUTH_DATABASE_TOKEN_HASH_SECRET"]
RESET_PASSWORD_TOKEN_SECRET = os.environ["LITESTAR_AUTH_RESET_PASSWORD_TOKEN_SECRET"]
VERIFY_TOKEN_SECRET = os.environ["LITESTAR_AUTH_VERIFY_TOKEN_SECRET"]

session_maker = async_sessionmaker[AsyncSession](
    class_=AsyncSession,
    expire_on_commit=False,
)


class UserManager(BaseUserManager[User, UUID]):
    """Customize hooks such as on_after_register as needed."""


config = LitestarAuthConfig[User, UUID](
    database_token_auth=DatabaseTokenAuthConfig(
        token_hash_secret=DATABASE_TOKEN_HASH_SECRET,
    ),
    user_model=User,
    user_manager_class=UserManager,
    session_maker=session_maker,
    user_manager_security=UserManagerSecurity(
        verification_token_secret=VERIFY_TOKEN_SECRET,
        reset_password_token_secret=RESET_PASSWORD_TOKEN_SECRET,
    ),
)
app = Litestar(plugins=[LitestarAuth(config)])

See Quickstart for a runnable pattern with the default User model and secrets.