Authentication: sessions, JWT and OAuth

Authentication answers "who are you?". Authorisation answers "what are you allowed to do?". Brew & Bean needs both: any customer can place an order, but only staff may change an order's status to preparing or ready.

What you'll build: a FastAPI service with /register, /login (returns a signed token), a protected /me route, and a staff-only route. Along the way you will learn how passwords must be stored, how sessions and JWTs differ, and what OAuth ("Sign in with Google") really does.

Prerequisites: Python 3.10+, basic FastAPI (see *Build an API with Python and FastAPI*) and curl. Input checking is covered in *Validation and error handling*, and the wider threat list in *API security essentials*.

If your database leaks and holds plain passwords, every user is exposed, and many reuse that password elsewhere. So you store a hash: a one-way scrambled form. To log in you hash what the user typed and compare. A password hash must be slow and salted on purpose, so guessing billions of passwords is expensive. Use a purpose-built algorithm such as bcrypt or Argon2. Never use plain MD5 or SHA-256 for passwords, and never invent your own scheme.

After login, the server must recognise the user on every later request, because HTTP forgets everything between requests. There are two common designs.

Session: the server creates a random session ID, stores the session data (who this is) on the server, in memory, a database or Redis, and sends the ID in a cookie. Each request carries the cookie and the server looks it up. It is simple and easy to log out (delete the session). It needs shared storage when you run several servers.

Token (JWT): the server gives the client a signed token that itself contains the user's id and an expiry. The client sends it in the Authorization: Bearer <token> header. The server checks the signature and needs no lookup. It suits APIs used by mobile apps and other services. The catch: a valid token cannot be easily cancelled before it expires.

Neither is "better". Many web apps are fine with sessions. This lesson builds the JWT version because most API job interviews ask about it.

A JWT (JSON Web Token) has three parts joined by dots: header.payload.signature. The header and payload are just Base64-encoded JSON, readable by anyone. The signature is made with the server's secret key, so if anyone changes the payload the signature check fails.

Typical payload fields are sub (the subject, here the user's email), exp (expiry time) and your own claims such as role.

import os
from datetime import datetime, timedelta, timezone

import bcrypt
import jwt
from fastapi import Depends, FastAPI, HTTPException
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
from pydantic import BaseModel, Field

SECRET_KEY = os.environ.get("JWT_SECRET", "dev-only-secret-change-me-before-deploying")
ALGORITHM = "HS256"
TOKEN_MINUTES = 30

app = FastAPI(title="Brew & Bean auth demo")
bearer = HTTPBearer()


def hash_password(password: str) -> str:
    return bcrypt.hashpw(password.encode(), bcrypt.gensalt()).decode()


def verify_password(password: str, password_hash: str) -> bool:
    return bcrypt.checkpw(password.encode(), password_hash.encode())


# A fake database: email -> user. Replace with a real table (see ORMs and migrations).
users: dict[str, dict] = {
    "barista@brewbean.in": {
        "email": "barista@brewbean.in",
        "password_hash": hash_password("barista-pass-123"),
        "role": "staff",
    }
}


class Credentials(BaseModel):
    email: str
    password: str = Field(min_length=8, max_length=64)


def create_token(email: str, role: str) -> str:
    payload = {
        "sub": email,
        "role": role,
        "exp": datetime.now(timezone.utc) + timedelta(minutes=TOKEN_MINUTES),
    }
    return jwt.encode(payload, SECRET_KEY, algorithm=ALGORITHM)


@app.post("/register", status_code=201)
def register(body: Credentials):
    if body.email in users:
        raise HTTPException(status_code=409, detail="Email already registered")
    users[body.email] = {
        "email": body.email,
        "password_hash": hash_password(body.password),
        "role": "customer",  # never let the client choose its own role
    }
    return {"email": body.email}


@app.post("/login")
def login(body: Credentials):
    user = users.get(body.email)
    # Same message for "no such user" and "wrong password"
    if user is None or not verify_password(body.password, user["password_hash"]):
        raise HTTPException(status_code=401, detail="Invalid email or password")
    return {"access_token": create_token(user["email"], user["role"]), "token_type": "bearer"}


def get_current_user(creds: HTTPAuthorizationCredentials = Depends(bearer)) -> dict:
    try:
        payload = jwt.decode(creds.credentials, SECRET_KEY, algorithms=[ALGORITHM])
    except jwt.ExpiredSignatureError:
        raise HTTPException(status_code=401, detail="Token expired")
    except jwt.InvalidTokenError:
        raise HTTPException(status_code=401, detail="Invalid token")
    user = users.get(payload["sub"])
    if user is None:
        raise HTTPException(status_code=401, detail="User no longer exists")
    return user


def require_role(role: str):
    def checker(user: dict = Depends(get_current_user)) -> dict:
        if user["role"] != role:
            raise HTTPException(status_code=403, detail="Not allowed")
        return user

    return checker


@app.get("/me")
def me(user: dict = Depends(get_current_user)):
    return {"email": user["email"], "role": user["role"]}


@app.patch("/orders/{order_id}/status")
def update_status(order_id: int, user: dict = Depends(require_role("staff"))):
    return {"order_id": order_id, "status": "preparing", "changed_by": user["email"]}

In-memory users dict stands in for a database table. The role is set by the server, never by the request.

Read the code in four parts.

1. Hashing. hash_password salts and hashes with bcrypt; verify_password compares. bcrypt only uses the first 72 bytes of a password, so the model caps passwords at 64 characters. 2. Register and login. Register refuses duplicate emails (409). Login returns the *same* message whether the email or the password was wrong, so attackers can't discover which emails exist. 3. The token. create_token puts sub, role and an expiry exp (30 minutes) into the payload and signs it with SECRET_KEY. PyJWT checks exp for you when decoding. 4. Dependencies. get_current_user reads the Bearer token, verifies it and loads the user. require_role("staff") builds on it. Any route that adds Depends(...) is protected.

# 1. Register
curl -X POST http://127.0.0.1:8000/register -H "Content-Type: application/json" -d '{"email":"asha@example.com","password":"filter-coffee-1"}'

# 2. Log in and copy the access_token from the response
curl -X POST http://127.0.0.1:8000/login -H "Content-Type: application/json" -d '{"email":"asha@example.com","password":"filter-coffee-1"}'

# 3. Call a protected route (replace TOKEN)
curl http://127.0.0.1:8000/me -H "Authorization: Bearer TOKEN"

# 4. Try the staff-only route with the customer token
curl -X PATCH http://127.0.0.1:8000/orders/1/status -H "Authorization: Bearer TOKEN"

On Windows PowerShell use curl.exe and swap the single quotes around JSON for double quotes with escaped inner quotes, or use the /docs page.

Step 4 returns 403 because you are authenticated but not authorised. Compare the codes: 401 means "I don't know who you are" (missing or bad token), 403 means "I know who you are, and you may not do this". Now log in as the seeded staff user barista@brewbean.in with password barista-pass-123 and repeat step 4: it succeeds.

OAuth 2.0 lets a user give your app limited access to their account on another service without giving you their password. "Sign in with Google" (built on OpenID Connect, a layer on top of OAuth) lets Google do the authentication and tell your app who the user is. The usual flow is called the authorization code flow.

Do not hand-write this in production. Use a maintained library (for Python, Authlib is a well-known one) or a service such as Auth0, Firebase Authentication or Keycloak. The security details (the state check, PKCE for public apps like mobile and single-page apps, token validation) are easy to get wrong. The provider's developer console is where you register your app to obtain the client_id and client_secret.

Expect: "How do you store passwords?" (salted slow hash such as bcrypt), "Session vs JWT?" (the table above), "Where do you store a JWT in the browser?" (trade-offs: an HttpOnly cookie is safer against XSS theft than localStorage, but then you need CSRF protection), "401 vs 403?" and "What is OAuth?" (delegated access through the authorization code flow). Be ready to say why JWTs are hard to revoke.

Act as a security reviewer for a FastAPI backend. Below is my authentication code. List weaknesses in order of severity, covering password storage, token creation and verification, secret handling, error messages, and role checks. For each, show the fix as a small code change.

[paste your main.py]

What to expect: A good review should mention secret management, token expiry, rate limiting on /login, HTTPS, and possible user-enumeration. Verify any library function it suggests exists before using it.