Week 6: Authentication with OAuth2 & JWT

1. Secure Password Hashing

A password column should never contain plaintext, and it should never contain anything reversible either — no encryption with a key you hold, because a key that can decrypt is a key that can also be stolen. Instead you store the output of a one-way hash function: something trivial to compute in one direction (password → digest) and computationally infeasible to reverse (digest → password). If your database ever leaks, an attacker gets a pile of digests, not credentials — and because people reuse passwords across sites, a plaintext leak on your side becomes a breach everywhere else that user has an account.

Not every hash function is suitable for passwords. SHA-256 is designed to be fast — great for checksumming a file, terrible for passwords, because "fast" also means an attacker with a GPU can try billions of guesses per second against a leaked digest. bcrypt is designed to be slow and tunable: it has a configurable cost factor (work factor) that exponentially increases the compute required per hash, so you can keep raising it as hardware gets faster without changing your code.

A salt is a random value generated per password and mixed in before hashing. Without one, two users with the password "password123" would produce the exact same digest, which lets an attacker precompute a table of common password hashes once (a "rainbow table") and look up matches instantly across every leaked database they find. With a unique salt per password, the same input produces a different digest every time, so precomputation stops working — the attacker has to brute-force each hash individually. bcrypt generates this salt for you automatically and stores it as part of the output string itself, so you never manage salts by hand.

from passlib.context import CryptContext

pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")


def hash_password(plain_password: str) -> str:
    return pwd_context.hash(plain_password)


def verify_password(plain_password: str, hashed_password: str) -> bool:
    return pwd_context.verify(plain_password, hashed_password)

pwd_context.hash generates the salt, applies bcrypt at the configured cost factor, and returns one self-contained string (algorithm identifier, cost, salt and digest all encoded together) that you store as-is:

from sqlalchemy.orm import Mapped, mapped_column
from sqlalchemy import String

class User(Base):
    __tablename__ = "users"

    id: Mapped[int] = mapped_column(primary_key=True)
    username: Mapped[str] = mapped_column(String(50), unique=True, index=True)
    hashed_password: Mapped[str] = mapped_column(String(255))

2. The OAuth2 Password Flow

OAuth2 is a broad authorization framework with several distinct "grant types" — different flows for different trust situations. The one this week uses is the Password Grant (formally, Resource Owner Password Credentials): a client collects a username and password directly and exchanges them with your own API for an access token. FastAPI ships two dependencies built specifically around this flow: OAuth2PasswordRequestForm, which parses the standard OAuth2 form fields (username, password, grant_type) out of a application/x-www-form-urlencoded request body, and OAuth2PasswordBearer, which extracts a bearer token from the Authorization header on protected routes and tells FastAPI's interactive docs where to send login requests.

This is not the same shape as "Login with Google." That's the Authorization Code grant: the user is redirected to Google, authenticates and consents there, and your backend receives a one-time code it exchanges server-to-server for a token — your application never sees the user's Google password at all. That indirection exists specifically because a third party owns the credential and needs to keep it away from every app that wants to use it. The password grant skips all of that because, in this course, you are the resource owner's application and the identity provider at the same time — there's no third-party credential to protect.

from fastapi import APIRouter, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordRequestForm

router = APIRouter()


@router.post("/token")
def login(form_data: OAuth2PasswordRequestForm = Depends()) -> dict[str, str]:
    user = get_user_by_username(form_data.username)
    if user is None or not verify_password(form_data.password, user.hashed_password):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Incorrect username or password",
            headers={"WWW-Authenticate": "Bearer"},
        )
    access_token = create_access_token(user.id)
    return {"access_token": access_token, "token_type": "bearer"}

Notice the endpoint returns the same generic error for "no such user" and "wrong password." Distinguishing them in the response would let an attacker enumerate valid usernames by watching which error comes back — the kind of detail that belongs in server logs, not in the HTTP response body.

3. Short-Lived Signed Access Tokens

A JSON Web Token is three base64url-encoded segments joined by dots: header.payload.signature. The header names the signing algorithm; the payload holds claims — arbitrary key/value data such as sub (subject, conventionally the user identifier) and exp (expiration, a Unix timestamp); the signature is computed over the header and payload using a secret key. Critically, a JWT is signed, not encrypted — anyone can base64-decode the payload and read it (paste one into jwt.io and see for yourself), but they cannot alter it without invalidating the signature, because they don't hold the secret used to produce it.

from datetime import datetime, timedelta, timezone
import jwt

def create_access_token(user_id: int) -> str:
    payload = {"sub": str(user_id), "exp": datetime.now(timezone.utc) + timedelta(minutes=15)}
    return jwt.encode(payload, settings.jwt_secret, algorithm="HS256")

HS256 is a symmetric algorithm — the same secret both signs and verifies tokens, which is fine as long as one backend does both. (If several independent services needed to verify tokens without being trusted to issue new ones, you'd switch to RS256: a private key signs, a public key verifies, and only the issuing service ever holds the private key.) The 15-minute exp is deliberate — it bounds how long a stolen token stays useful. jwt.decode checks the signature and the expiration in one call, so verifying "is this token still good" never requires a database lookup.

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

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")


def get_current_user(token: str = Depends(oauth2_scheme)) -> User:
    credentials_error = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="Could not validate credentials",
        headers={"WWW-Authenticate": "Bearer"},
    )
    try:
        payload = jwt.decode(token, settings.jwt_secret, algorithms=["HS256"])
    except jwt.ExpiredSignatureError:
        raise credentials_error
    except jwt.InvalidTokenError:
        raise credentials_error

    user = get_user_by_id(int(payload["sub"]))
    if user is None:
        raise credentials_error
    return user

jwt.decode raises ExpiredSignatureError specifically when exp has passed, and the broader InvalidTokenError (its superclass, which also covers a bad signature, malformed token, or wrong algorithm) for everything else that makes a token untrustworthy. Both collapse to the same 401 here — the caller doesn't need to know why their token was rejected, only that they need to authenticate again.

4. Hands-on Exercise

5. Knowledge Check

Four quick questions. Expand each to check your answer.