Auth & Security — Cheat Sheet

OAuth2 Password Flow — Login That Issues Tokens

from fastapi import Depends, FastAPI, HTTPException, status
from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm

app = FastAPI()

# Extracts "Authorization: Bearer xyz" → "xyz"; 401 if header missing
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

FAKE_DB = {"asha@nitk.edu.in": {"name": "Asha", "hashed": "bcrypt$..."}}

@app.post("/token")
def login(form: OAuth2PasswordRequestForm = Depends()):
    user = FAKE_DB.get(form.username)          # form fields: username, password
    password_ok = user is not None             # verify_password() → next chapter
    if not user or not password_ok:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="incorrect username or password",   # deliberately vague:
            headers={"WWW-Authenticate": "Bearer"},    # never reveal WHICH was wrong
        )
    return {
        "access_token": "fake-token-" + form.username,   # real JWT → next chapter
        "token_type": "bearer",                          # spec-required shape
    }

@app.get("/profile")
def profile(token: str = Depends(oauth2_scheme)):
    return {"your_token": token}     # decoding it comes next

# The wire format:
#   POST /token   Content-Type: application/x-www-form-urlencoded
#   username=asha%40nitk.edu.in&password=s3cret
#   → {"access_token": "...", "token_type": "bearer"}
#   GET /profile  Authorization: Bearer <access_token>

Password Hashing — bcrypt/Argon2 Done Right

# pip install "pwdlib[argon2,bcrypt]"

from pwdlib import PasswordHash

pwd = PasswordHash.recommended()        # Argon2id today; updated as research moves

# ── registration ──
h1 = pwd.hash("MySecret@2026")
h2 = pwd.hash("MySecret@2026")
print(h1 == h2)                         # False — unique salt baked into each hash
print(h1)                               # $argon2id$v=19$m=65536,t=3,p=4$...salt...$...

# ── login ──
print(pwd.verify("MySecret@2026", h1))  # True
print(pwd.verify("MySecret@2026", h2))  # True — salt read from the hash itself
print(pwd.verify("wrong-guess",  h1))   # False (constant-time comparison inside)

# Why NOT sha256:
#   import hashlib; hashlib.sha256(b"pass").hexdigest()
#   - designed to be FAST → GPU rigs try tens of billions of guesses/second
#   - unsalted → one rainbow table cracks every user with "password@123"
#   Argon2/bcrypt: ~50-300ms EACH by design, unique salt per hash →
#   the same leak takes centuries instead of a weekend.

# Cost tuning: aim ~100-300ms per hash on YOUR production hardware —
# slow enough to hurt attackers, fast enough for login UX.

JWT — Creating and Verifying Tokens

# pip install pyjwt

from datetime import datetime, timedelta, timezone
import jwt
from fastapi import Depends, FastAPI, HTTPException
from fastapi.security import OAuth2PasswordBearer

SECRET = "from-Settings-never-hardcoded"     # settings.jwt_secret, 32+ random bytes
ALGO = "HS256"
TTL = timedelta(minutes=30)

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

def create_access_token(email: str, role: str) -> str:
    now = datetime.now(timezone.utc)
    claims = {
        "sub": email,                        # subject — whose token
        "role": role,                        # custom claim (readable by anyone!)
        "iat": now,                          # issued at
        "exp": now + TTL,                    # pyjwt REJECTS after this, automatically
    }
    return jwt.encode(claims, SECRET, algorithm=ALGO)

def get_current_user(token: str = Depends(oauth2_scheme)) -> dict:
    try:
        claims = jwt.decode(token, SECRET, algorithms=[ALGO])   # verifies sig + exp
    except jwt.ExpiredSignatureError:
        raise HTTPException(401, "token expired",
                            headers={"WWW-Authenticate": "Bearer"})
    except jwt.InvalidTokenError:            # bad signature, malformed, wrong algo
        raise HTTPException(401, "invalid token",
                            headers={"WWW-Authenticate": "Bearer"})
    return {"email": claims["sub"], "role": claims["role"]}

@app.get("/profile")
def profile(user: dict = Depends(get_current_user)):
    return user

# eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhc2hhQG5pdGsu...  ← header.payload.signature
# The payload is only base64 — decodable by ANYONE (jwt.io).
# The signature is what stops modification. Secrets do NOT belong in claims.

RBAC & Scopes — Roles, Permissions, Ownership

from fastapi import Depends, FastAPI, HTTPException

app = FastAPI()

ROLE_PERMISSIONS = {
    "student": {"drives:read", "applications:create", "profile:write"},
    "tpo":     {"drives:read", "drives:create", "drives:close",
                "students:read", "reports:read"},
    "admin":   {"*"},                                # everything
}

def require_permission(permission: str):
    def checker(user: dict = Depends(get_current_user)) -> dict:   # JWT chapter
        perms = ROLE_PERMISSIONS.get(user["role"], set())
        if "*" not in perms and permission not in perms:
            raise HTTPException(403, f"requires permission: {permission}")
        return user
    return checker

@app.post("/drives", status_code=201)
def create_drive(user: dict = Depends(require_permission("drives:create"))):
    return {"created_by": user["email"]}

@app.get("/reports/placements")
def placement_report(user: dict = Depends(require_permission("reports:read"))):
    return {"placed": 212, "total": 260}

# Why permissions beat raw roles:
#   "TPOs can now also close drives" → add one string to the tpo set. Done.
#   New "placement-coordinator" role → one new dict entry. Done.
#   With require_role("tpo") sprinkled on endpoints, both changes mean
#   hunting every endpoint that mentions a role. The map is the policy.

# At scale the map moves to the DB (editable per tenant), and the
# gyaan-api pattern applies: org_id scoping + role per membership.