Skip to content

fastapi-simple-tinyauth

Simple forward-auth integration for FastAPI apps sitting behind Tinyauth or any reverse proxy that authenticates users and forwards their identity as HTTP headers.

fastapi-simple-tinyauth gives you a small, explicit auth layer:

  • A pure-ASGI TinyauthMiddleware that reads the identity headers your proxy forwards and stores an AuthUser on request.state.auth_user.
  • FastAPI dependencies — require_user, optional_user, and the group helpers require_group, require_all_groups, require_any_group.
  • A mandatory trusted proxy allowlist so forwarded headers are only trusted when they come from a proxy you control.
  • Custom exceptions that derive from HTTPException, so you can register exception_handlers.

Design at a glance

The flow is deliberately simple:

  • Your reverse proxy (Tinyauth) authenticates the user and forwards their identity as headers: Remote-User, Remote-Email, Remote-Name, Remote-Groups, Remote-Sub.
  • The middleware first checks that the request's immediate TCP peer is a trusted proxy. If not, it rejects the request with HTTP 403 — untrusted clients cannot spoof the headers.
  • For a trusted peer, the headers are parsed into an AuthUser. A request without Remote-User is treated as anonymous.
  • Endpoints read the user through dependencies, requiring authentication or group membership as needed.

Continue with Getting started.

Development note

This code was developed mostly with AI (vibe coding), but has been reviewed and validated by a human.