Introduction to Security (FastAPI)

"Security isn't a feature you flip on at the end. It's a design choice you bake into every request." — Probably someone who wrote a secure API once and is still slightly smug about it.

You're coming in hot from the Dependency Injection section (where we lovingly weaponized Depends, yields, and parameterized factories). Good. You already know how to compose logic cleanly and reuse code across routes. Now we turn that composability into your security posture — because the exact same patterns that make your app modular also make it easier to protect.

---

Why this matters (and why you'll thank me later)

• Authentication = proving who a client is ("Hey, it's me — Alice!").
• Authorization = deciding what that authenticated client can do ("Okay, Alice can read invoices but not delete them").
• Security dependencies in FastAPI let you define these checks once and inject them everywhere, keeping endpoints readable and consistent.

Imagine writing the same token-checking code in 30 handlers. Now imagine debugging it when your auth logic breaks. Dependency injection saves your future self a lot of crying and late-night patching.

---

The building blocks

1) FastAPI security utilities

FastAPI ships helpers in fastapi.security:

• OAuth2PasswordBearer — common for token-based auth flows.
• OAuth2PasswordRequestForm — helper to read username/password from a token request form.
• HTTPBasic, HTTPBearer, APIKeyHeader/Cookie/Query — different styles of credentials.

Use these to parse where credentials come from; use your dependencies to verify them.

2) Dependencies as security gates

This is the good part: create small, testable dependencies that validate credentials and return the authenticated user or throw an HTTPException. Then use Depends(...) or Security(...) at route definition time.

Example: a simple get_current_user dependency using OAuth2 and a JWT (illustrative only):

from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from jose import jwt, JWTError

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/token")

SECRET_KEY = "SUPER_SECRET_KEY"  # NO. Keep this out of source control.
ALGORITHM = "HS256"

def get_current_user(token: str = Depends(oauth2_scheme)):
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
        username: str = payload.get("sub")
        if username is None:
            raise credentials_exception
    except JWTError:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Could not validate credentials",
            headers={"WWW-Authenticate": "Bearer"},
        )
    # Fetch user from DB here
    return {"username": username}

Then protect your endpoint:

@app.get("/me")
def read_users_me(current_user: dict = Depends(get_current_user)):
    return current_user

Notice how neat this is compared to copy-pasting token logic everywhere? That's dependency injection + security synergy.

---

Patterns and recipes (you'll use these a lot)

Reusable, parameterized security dependencies

You can create factories that return a dependency configured for a particular role or permission (remember parameterized dependencies!). Example:

from fastapi import Depends

def require_role(role: str):
    def _require_role(user: dict = Depends(get_current_user)):
        if user.get("role") != role:
            raise HTTPException(status_code=403, detail="Forbidden")
        return user
    return _require_role

# Usage
@app.post("/admin/create")
def create_admin_item(user=Depends(require_role("admin"))):
    ...

This is dangerously clean: define once, apply everywhere.

Using yields for resource-safe security

If your auth verification needs a DB connection or external resource, reuse your yield-style dependency pattern (from "Dependencies with Yields"). That ensures sessions are cleaned up even when auth fails:

from dependencies import get_db  # imagine this is a yield-based DB session

def get_current_user(db=Depends(get_db), token: str = Depends(oauth2_scheme)):
    # decode token then query db for user; get_db will be closed automatically
    ...

---

Quick comparison: common auth approaches

Method	When to use	Pros	Cons
HTTP Basic	Internal or legacy	Simple	Sends creds each request (use HTTPS)
Session Cookie	Web UIs	Easy CSRF defense, established flow	Stateful, needs storage
JWT / Bearer Token	APIs, microservices	Stateless, scalable	Revocation is harder
OAuth2 (with PKCE)	Third-party auth	Standardized, secure	More complex
API Keys	Service/service or dev APIs	Simple to implement	Hard to rotate & scope

Ask: What are you building — B2B API, public mobile API, internal microservice? Let that decide the approach.

---

Common pitfalls (read this and avoid my past mistakes)

• Never hard-code secrets. Use env vars, vaults, or secret managers.
• Always use HTTPS for tokens and credentials.
• Don’t roll your own crypto. Use libraries (e.g., PyCA, jose, passlib).
• JWTs are not a magic bullet: implement rotation, expiry, and revocation strategies.
• Keep auth logic out of handlers — dependencies are testable and reusable.

---

Interactivity: Questions to make you smarter

• If your API is used by both browser-based UIs and mobile apps, would you prefer session cookies or JWTs? Why?
• How would you implement immediate token revocation for compromised keys in a stateless JWT system?
• Imagine a role hierarchy (admin > editor > user). How would you structure a parameterized dependency to handle hierarchical checks?

Try answering these in code — and then test them.

---

Closing — TL;DR and what to build next

• Security in FastAPI = parse credentials (fastapi.security) + validate via dependencies (your business logic).
• Reuse and parameterize those dependencies — they make your app safer and your code saner.
• Use yield-style dependencies when you need resource management (DBs, external calls) during auth.

Next steps: implement an OAuth2 token endpoint using OAuth2PasswordRequestForm, password hashing (passlib), and JWT issuance. After that, explore scopes with Security(...) and integrate third-party providers (OAuth with Google, GitHub) for delegation.

"Good security is boring, loud failures are dramatic." Keep it boring, folks. Make the drama happen only in logs, not your users' inboxes.

---

Version note: This lesson builds on your mastery of dependency injection (parameterization and yields) — the same patterns make your authentication code composable, testable, and maintainable.