fastapi-dependency-injection

Files (1)

• SKILL.md

SKILL.md (first lines)

# FastAPI Dependency Injection

> Defends against **OWASP ASI03 (Identity & Privilege Abuse)** in
> FastAPI applications where the DI graph carries auth-relevant state.
> FastAPI's DI system is ergonomic for wiring shared dependencies
> (database sessions, settings, repositories), but its scoping model is
> per-request only by default -- and that semantic interacts subtly with
> auth-token handling. Without the patterns here, request-scoped
> identity can leak across requests via inadvertent caching, or
> auth-required routes can ship without an enforced auth check because
> the DI declaration was forgotten.

**Tradeoff:** Explicit `Depends()` declarations on every auth-required
route is repetitive vs. relying on global middleware. Worth it:
per-route auth dependencies are reviewable in isolation, can be
overridden in tests for the specific route, and produce typed access
to the authenticated identity inside the handler. Middleware-only auth
hides the contract from the handler signature.

---

## Why this matters

FastAPI's `Depends()` system resolves dependencies per request by
default -- new database session, fresh auth check, freshly-loaded
settings. But the framework also supports `lru_cache`-style memoization
for expensive dependencies (settings loading, model loading). If an
auth-related dependency is inadvertently memoized at the wrong scope,
the first request's identity propagates to all subsequent requests
hitting the same worker process. The error is silent: the test suite
passes (one request, one identity), production fails (many requests,
same memoized identity).

Separately, `dependency_overrides` -- FastAPI's testing affordance
that replaces a dependency for a test run -- is a global mutation on
the app's DI registry. A test that forgets to clean up its override
leaves the override in place for every later test in the session, so
those tests exercise a fake identity instead of the real auth check.

---

## Pattern 1 -- Declare auth as a `Depends` on every protected route, never via middleware-only

```python
from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from pydantic import BaseModel

app = FastAPI()
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

class User(BaseModel):
    id: str
    email: str

async def get_current_user(token: str = Depends(oauth2_scheme)) -> User:
    """Verify the token and return the authenticated user.

    Returns a fresh User instance per request -- the function body
    runs on each request, so no cross-request identity leakage.
    """
    user = await verify_token_against_session_store(token)
    if user is None:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="invalid or expired token",
        )
    return user

@app.get("/profile")
async def read_profile(current_user: User = Depends(get_current_user)) -> dict:
    # current_user is the per-request authenticated identity, typed
    # and visible in the handler signature -- a reviewer sees the auth
    # requirement directly without reading middleware config.
    return {"id": current_user.id, "email": current_user.email}
```

The auth requirement appears in the route signature. A new route that
omits `Depends(get_current_user)` is immediately reviewable as
unauthenticated -- there's no hidden middleware behavior masking the
absence.

For broad-application auth requirements (e.g., every route under
`/admin/**` requires admin role), use a `dependencies=` list on a
sub-router or `APIRouter` so the dependency is still visible at the
route-group level:

```python
from fastapi import APIRouter, Depends
from .auth import require_admin

admin_router = APIRouter(
    prefix="/admin",
    dependencies=[Depends(require_admin)],  # applies to every route under /admin
    tags=["admin"],
)
```

---

## Pattern 2 -- Scope expensive-to-construct dependencies correctly

```python
from functools import lru_cache
from fastapi import Depends
from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    model_config = SettingsConfigDict(env_file=".env")
    database_url: str
    api_key: str
    feature_flags: dict[str, bool] = {}

@lru_cache(maxsize=1)
def get_settings() -> Settings:
    """Settings are app-wide and immutable -- safe to memoize."""
    return Settings()

# In a route:

From MILTONADINA/DevOPs, MIT.

More from MILTONADINA/DevOPs