module-5

---
name: module-5
description: Teaching instructions for Module 5 (Authentication and Authorization) — use when module_id is module-5
---

# Module 5 — Authentication and Authorization

## Lesson Title
Authentication and Authorization in a Multi-Tenant Deployment

## Goal
Walk the student through adding real auth to a LangGraph deployment: first identifying users (`@auth.authenticate`), then scoping their access to resources (`@auth.on`), then swapping the toy token store for a real identity provider, then wiring it into the tutor agent.

## How to run this lesson
- Start with the **distinction**: authentication answers "who is this?", authorization answers "what can they do?". The two decorators map cleanly to those two questions.
- Walk through m5.1's request-pipeline diagram before touching code. Students should know where in the request lifecycle the auth handler runs.
- For m5.2 (local auth), emphasize that `@auth.authenticate` is the ONLY interception point and that its return value flows into the rest of the request.
- For m5.3 (private conversations), the key idea is metadata stamping on writes + filter dict on reads. Bob gets a 404 (not 403) on Alice's thread because the filter makes the thread invisible — there's nothing to forbid.
- For m5.4 (Supabase), call out that the `@auth.on` handler from m5.3 does NOT change — only `@auth.authenticate` is swapped. This is the payoff for keeping auth and authz decoupled.
- For m5.5 (tutor), reinforce that `deep_tutor`'s `store_namespace` is email-derived (independent of auth identity). Auth gates "can this user call?" while namespace decides "where does their data live?". They meet in `@auth.on.store()`.

## Key concepts to cover
1. `@auth.authenticate` — receives the raw `Authorization` header, returns a `MinimalUserDict` with at minimum `identity`, or raises `Auth.exceptions.HTTPException(401)`
2. `@auth.on` — fires after authenticate, on every resource access; stamps metadata on writes and returns a filter dict on reads
3. The `langgraph.json` registration — `auth.path = "./auth.py:auth"` is what wires the handler in
4. Scoped vs broad handlers — `@auth.on.threads.create` is more specific than `@auth.on`; most specific wins
5. Why Bob gets a 404 (filter, not deny) — the resource is invisible, not forbidden
6. `@auth.on.store()` is different — no automatic filter, the handler asserts/raises to allow/block; namespace[0] convention
7. Swapping the token store — from hardcoded dict (m5.2) to Supabase JWT validation (m5.4); only `@auth.authenticate` changes
8. Two access paths to the authenticated user — `ctx.user.identity` in `@auth.on` handlers, `runtime.server_info.user.identity` in graph nodes
9. The OAuth2 three-role model — Client App, Auth Provider, Agent Server; the Agent Server never stores credentials
10. Auth vs namespace in `deep_tutor` — auth gates calls; `context.store_namespace` (email-derived) decides where data lives; meeting point is `@auth.on.store()`

## Tone guidance
Precise about the contract — students often confuse authentication with authorization. Hammer the separation. When discussing examples, refer to Alice/Bob/admin (the lesson personas) so the student can connect explanations to concrete lab runs.

## Reference material
Full reference material is in `information.md` in this directory. Read it before answering factual questions.