How fastapi-users/fastapi-users works
Project type and purpose
• Type: Open-source Python library (plugin) for FastAPI.
• Purpose: Provide ready-to-use, customizable routes and logic for user registration, authentication (JWT, database, Redis), password reset, email verification, OAuth2 social login, and full OpenAPI schema support.
High-level file-structure analysis
• Top-level directories:
– fastapi_users/: core library code (authentication, router, db adapters, manager, schemas, models, OpenAPI).
– examples/: sample FastAPI apps demonstrating different database backends and OAuth flows.
– docs/: MkDocs-based documentation, configuration guides, and code snippets.
– tests/: unit tests covering all strategies, transports, managers, routers, and OpenAPI.
• Configuration/build: Hatch for environment and tasks, GitHub Actions workflows, mkdocs.yml, pyproject.toml.
Key insights from README
• Modular, extensible design with clear extension points:
– Pluggable authentication backends (strategies + transports).
– Swappable database adapters (SQLAlchemy async ORM, Beanie ODM).
– Ready-to-mount FastAPI routers for each user flow.
• Examples show how host apps call into the library.
Main components
A. Host FastAPI Application (external)
• Registers the FastAPI Users instance and mounts routers.
• Supplies: user model, database session, secret keys, email sender, OAuth client config.
B. fastapi_users Library (internal)
1. Router Layer
– auth.py, register.py, reset.py, verify.py, users.py, oauth.py
– Exposes HTTP endpoints: POST /register, POST /login, GET /verify, etc.
2. Authentication Layer
a. Transports (fastapi_users/authentication/transport):
• bearer.py (Authorization header)
• cookie.py
b. Strategies (fastapi_users/authentication/strategy):
• jwt.py
• db/strategy.py (database sessions)
• redis.py
c. Authenticator (authenticator.py) orchestrates strategy + transport.
3. Manager (manager.py)
– Business logic: hashing passwords, generating tokens, sending emails, verifying codes.
4. Database Adapters (fastapi_users/db)
– Base adapter, SQLAlchemy, Beanie implementations.
– Models (adapter.py), CRUD operations.
5. Schemas & Models
– Pydantic schemas (UserCreate, UserRead, UserUpdate) and ORM models.
6. OpenAPI Integration (openapi.py)
– Merges multiple auth backends into FastAPI’s security schemes.
C. External Services
• Relational Database (PostgreSQL/MySQL via SQLAlchemy)
• MongoDB (via Beanie)
• Redis (optional session/token store)
• Email service (SMTP or third-party)
• OAuth2 Providers (Google, Facebook, etc.)
Relationships & data flows
1. Client → HTTP Request → FastAPI App
2. FastAPI App → Mounted Router → Endpoint handler
3. Endpoint handler → Authenticator
– Transport extracts credentials from header/cookie.
– Strategy verifies credentials (JWT decode or DB lookup or Redis).
4. On registration/reset/verify: Handler calls Manager → generates token/reset link → sends via Email service.
5. Manager/Authenticator → Database Adapter → External Database
6. Authenticator → issues or validates JWT tokens or session IDs → returns to client via transport.
Architectural patterns & principles
• Modular layering (Router → Authenticator → Manager → DB).
• Dependency injection (FastAPI dependencies for current_user, DB session).
• Strategy pattern for authentication and transport.
• Adapter pattern for multiple databases.
• OpenAPI auto-generation via schema introspection.