Login e rotte protette
Il biglietto si prende una volta, e si mostra a ogni porta
- 15 minuti di lettura
Nei capitoli di prima hai messo insieme i pezzi: l'impronta della password (capitolo 4) e il biglietto firmato (capitolo 5). Qui li metti dentro un'API vera, e succede la cosa che si vede: una porta che si apre solo a chi ha il biglietto giusto.
Sono tre mosse, sempre le stesse:
- il login: una rotta che prende username e password e restituisce il biglietto;
- il controllore: una funzione che a ogni richiesta guarda il biglietto e dice chi sei;
- la rotta protetta: una rotta che usa il controllore, con una riga sola.
UNA VOLTA SOLA A OGNI PORTA
username + password GET /me GET /turni/mio
│ │ │
▼ ▼ ▼
POST /login ┌─────────────────────────────────────────┐
│ │ il controllore: utente_corrente │
▼ │ guarda il biglietto, dice chi sei │
il biglietto ──── lo tieni ────▶ └────┬──────────────────────────┬─────────┘
(access_token) e lo mostri │ biglietto buono │ altrimenti
a ogni richiesta ▼ ▼
la rotta parte 401, e la rotta non parteIl login
POST /login riceve le credenziali (username e password, in JSON) e fa tre cose: cerca l'utente, controlla la password, stampa il biglietto. Gli attrezzi sono già in sicurezza.py: password_giusta controlla, crea_biglietto stampa.
@app.post("/login")
def login(dati: Credenziali) -> Biglietto:
utente = utenti.get(dati.username)
if utente is None or not password_giusta(dati.password, utente.password_hash):
raise HTTPException(status_code=401, detail="Username o password sbagliati")
return Biglietto(access_token=crea_biglietto(utente.username), token_type="bearer")Riga per riga:
utenti.get(dati.username): l'utente, oppureNonese lo username non c'è. Con le quadre sarebbe unKeyError, cioè un 500.utente is None or not password_giusta(...): un soloifper due guai. Lo username non c'è? Oppure c'è ma la password non è la sua? Il risultato è lo stesso: 401. SeutenteèNone, Python si ferma al primo pezzo dell'ore non guarda nemmeno la password.- Il biglietto porta dentro lo username (
utente.username), non il nome: è la parola con cui il controllore ritroverà l'utente nel dizionario.
Biglietto è lo stampo della risposta: access_token è il biglietto (il nome lo vuole lo standard: access token vuol dire «gettone di accesso», e a volte si dice solo token), token_type dice sempre "bearer". Con curl:
curl -i -X POST http://127.0.0.1:8000/login -H "Content-Type: application/json" -d '{"username": "lucia", "password": "sbagliata-123"}'
curl -s -X POST http://127.0.0.1:8000/login -H "Content-Type: application/json" -d '{"username": "mapelli", "password": "capotreno-M12"}'
curl -s -X POST http://127.0.0.1:8000/login -H "Content-Type: application/json" -d '{"username": "lucia", "password": "capotreno-M12"}'HTTP/1.1 401 Unauthorized
date: Thu, 19 Nov 2026 18:11:14 GMT
server: uvicorn
content-length: 42
content-type: application/json
{"detail":"Username o password sbagliati"}
{"detail":"Username o password sbagliati"}
{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJsdWNpYSIsImV4cCI6MTc5NTExMzY3NX0.o1bJgddUZBbmsuq4utzVS013Axm0Hp95NCw0GJYq5lQ","token_type":"bearer"}Il biglietto che vedi tu sarà diverso: dentro c'è l'ora di scadenza, e la chiave è la tua.
Dove sta il biglietto: l'header
Dopo il login il biglietto lo tieni tu. A ogni richiesta lo mostri, in un header (la riga di intestazione della richiesta, come nel viaggio di una richiesta) che si chiama Authorization:
GET /me HTTP/1.1
Host: 127.0.0.1:8000
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJsdWNpYSIsImV4cCI6MTc5NTExMzY3NX0.o1bJgddUZBbmsuq4u…Il valore è la parola Bearer, uno spazio, il biglietto. Bearer vuol dire «portatore»: chi porta il biglietto è chi entra. Lo spazio conta, e conta anche la parola: senza Bearer il controllore non riconosce niente.
Leggere quella riga e spezzarla in due pezzi lo fa HTTPBearer, di FastAPI. In sicurezza.py c'è già, con il nome controllore:
controllore = HTTPBearer(auto_error=False)Messo in un parametro con Depends, ti consegna un oggetto con due campi (scheme, la parola, e credentials, il biglietto), oppure None:
| L'header della richiesta | Cosa riceve la tua funzione |
|---|---|
Authorization: Bearer eyJabc.def.ghi | un oggetto con scheme uguale a "Bearer" e credentials uguale a "eyJabc.def.ghi" |
| nessun header | None |
Authorization: Basic … (un altro tipo di accesso) | None |
Authorization: eyJabc.def.ghi (manca la parola Bearer) | None |
Il primo caso, come lo vede la tua funzione:
Lo vedi con i tuoi occhi nell'esempio B degli esercizi spiegati.
header.credentials è il biglietto, senza la parola Bearer. E None (qui null) arriva in tre casi: l'header non c'è, non comincia con Bearer, manca lo spazio.
Dalla chiave al biglietto: quattro cambi
Il controllore che stai per leggere non è una cosa nuova: è controlla_chiave del capitolo 3, con quattro cambi. Tutto il resto è uguale: una funzione senza @app, due 401, raise che ferma e return che finisce nel parametro, Depends senza parentesi nella rotta.
controlla_chiave (la chiave) | utente_corrente (il biglietto) | |
|---|---|---|
| 1. L'header | X-API-Key: …, letto con Header(default=None, alias="X-API-Key") | Authorization: Bearer …, letto da controllore (HTTPBearer) con Depends(controllore) |
| 2. Il confronto | chiave != CHIAVE_MAGAZZINO: è uguale alla copia nel .env? | leggi_biglietto(header.credentials): la firma torna, non è scaduto? |
| 3. Chi sei | la chiave dice solo quale programma: "Valdora Ricambi" | il biglietto porta lo username: utenti.get(username) cerca l'utente |
4. Il return | il nome del fornitore | l'utente, UtenteSalvato |
Anche i messaggi hanno lo stesso schema: «Manca la chiave» diventa «Manca il biglietto», «Chiave sbagliata» diventa «Biglietto non valido».
Il controllore: utente_corrente
Il controllore è una funzione normale che scrivi tu. Riceve l'header già letto e deve restituire l'utente, oppure fermare tutto con un 401:
def utente_corrente(header: HTTPAuthorizationCredentials | None = Depends(controllore)) -> UtenteSalvato:
if header is None:
raise HTTPException(status_code=401, detail="Manca il biglietto")
username = leggi_biglietto(header.credentials) # None se il biglietto non vale
utente = utenti.get(username) # None anche se l'utente non c'è più
if utente is None:
raise HTTPException(status_code=401, detail="Biglietto non valido")
return utenteTre domande, nell'ordine:
- C'è un biglietto? Se
headerèNone: 401, «Manca il biglietto». Senza questa riga, il passo dopo scriveheader.credentialssu unNonee il server risponde 500. - Il biglietto vale?
leggi_biglietto(la scrivi nel capitolo 5, qui è già pronta) controlla firma e scadenza e restituisce lo username, oppureNone. - Quell'utente esiste ancora?
utenti.get(username). Conusernameuguale aNoneilgetdàNonee basta, senza errori: così le domande 2 e 3 finiscono nello stessoif, con lo stesso messaggio, «Biglietto non valido».
Il tipo del parametro, HTTPAuthorizationCredentials | None, dice a chi legge che il controllore può passare None: è proprio il caso della domanda 1.
La rotta protetta: una riga
utente_corrente è una dipendenza, come get_db nel capitolo sulla sessione: FastAPI la chiama prima della rotta, e quello che restituisce arriva nel parametro. Anzi, qui ci sono due dipendenze una dentro l'altra: la rotta usa utente_corrente, e utente_corrente usa controllore. FastAPI le risolve da dentro a fuori.
@app.get("/me")
def chi_sono(utente: UtenteSalvato = Depends(utente_corrente)) -> Utente:
return utenteIl parametro utente: UtenteSalvato = Depends(utente_corrente) è l'unica riga che protegge la rotta. Se il controllore ferma tutto con un 401, la funzione chi_sono non parte nemmeno. Se lo passa, dentro chi_sono utente è già l'utente vero, quello del biglietto.
E il -> Utente? È lo stampo della risposta (capitolo 4): utente è un UtenteSalvato, con l'impronta, ma la risposta tiene solo username e nome. Senza quella freccia (o con -> UtenteSalvato) l'impronta uscirebbe.
curl -s http://127.0.0.1:8000/me -H "Authorization: Bearer $BIGLIETTO"
curl -i http://127.0.0.1:8000/me
curl -s http://127.0.0.1:8000/me -H "Authorization: $BIGLIETTO"
curl -s http://127.0.0.1:8000/me -H "Authorization: Bearer biglietto-disegnato-a-mano"{"username":"lucia","nome":"Lucia Ferri"}
HTTP/1.1 401 Unauthorized
date: Thu, 19 Nov 2026 18:11:14 GMT
server: uvicorn
content-length: 31
content-type: application/json
{"detail":"Manca il biglietto"}
{"detail":"Manca il biglietto"}
{"detail":"Biglietto non valido"}Nella terza chiamata il biglietto c'è, ma manca la parola Bearer: per il controllore è come se non ci fosse.
Le cinque strade del 401
Un biglietto può non andare bene in cinque modi. Li fermano leggi_biglietto e utente_corrente, uno dopo l'altro:
la richiesta arriva a GET /me
│
▼
1 c'è un header «Authorization: Bearer …»? no ──▶ 401 «Manca il biglietto»
│ sì (utente_corrente, con header None)
▼
2 è un JWT? no ──▶ 401 «Biglietto non valido»
│ sì (leggi_biglietto)
▼
3 la firma torna? (nessuno ha cambiato il payload) no ──▶ 401 «Biglietto non valido»
│ sì (leggi_biglietto)
▼
4 è ancora valido? (exp non è passato) no ──▶ 401 «Biglietto non valido»
│ sì (leggi_biglietto)
▼
5 l'utente esiste ancora nel dizionario? no ──▶ 401 «Biglietto non valido»
│ sì (utente_corrente)
▼
la rotta parte, con l'utente giustoTutti 401: non so chi sei. Il 403 («so chi sei, ma qui non entri») non c'è ancora: arriva nel capitolo sui permessiin arrivo. Per ricordare l'ordine delle domande: prima il biglietto (401), poi la cosa che chiedi esiste? (404), poi puoi vederla? (403). Lo vedi nella storia di questo capitolo, dove una porta che non c'è risponde 404 solo a chi ha un biglietto buono.
Chi sei lo dice il biglietto
Una regola, la più importante del capitolo: l'utente lo decide il biglietto, non la richiesta.
Mai uno username preso dal corpo, mai dall'indirizzo o da un parametro (/turni/mio?username=lucia): chiunque può scrivere il nome che vuole. Il biglietto no: è firmato con la chiave, e chi non la conosce non può cambiarlo. Per questo la rotta si chiama /me e /turni/mio: «mio» di chi ha il biglietto, senza dire di chi.
@app.get("/turni/mio")
def il_mio_turno(utente: UtenteSalvato = Depends(utente_corrente)) -> dict[str, str]:
turno = TURNI.get(utente.username) # lo username arriva dal biglietto, tramite utente_corrente
if turno is None:
raise HTTPException(status_code=404, detail="Turno non trovato")
return {"username": utente.username, "turno": turno}Provarla dal vivo
Tre modi, tutti a partire da fastapi dev (come negli esercizi: fastapi dev palestra/controllore.py).
Da /docs. Apri http://127.0.0.1:8000/docs. POST /login → Try it out → scrivi username e password nel corpo → Execute. Dalla risposta copia il valore di access_token (senza virgolette). In alto a destra, il lucchetto Authorize: incolla il biglietto, conferma. Da lì in poi /docs lo manda in ogni richiesta. Il lucchetto compare perché la rotta usa HTTPBearer: ecco a cosa serve.
Da curl. Quello che hai visto sopra. Il biglietto, per non ricopiarlo ogni volta, si mette in una variabile del terminale: BIGLIETTO=$(curl -s … | python3 -c …), e poi -H "Authorization: Bearer $BIGLIETTO".
Da Postman. L'app desktop (su Windows si installa su Windows, non nel terminale di Ubuntu: raggiunge lo stesso l'API accesa in WSL). Le basi, cioè collezione e variabili, sono nel capitolo su Postman e curl. Il giro del login è questo:
- Nella collezione, la variabile
baseUrlvalehttp://127.0.0.1:8000. - Richiesta POST a
{{baseUrl}}/login. Body → raw → JSON, con{"username": "lucia", "password": "capotreno-M12"}. - Nella scheda Scripts → Post-response, questa riga, che prende
access_tokendalla risposta e lo salva nella variabilebiglietto:
pm.collectionVariables.set("biglietto", pm.response.json().access_token);- Nelle richieste protette: Authorization → Auth Type → Bearer Token →
{{biglietto}}. Postman scrive da solo l'headerAuthorization: Bearer ….
Il biglietto dura 30 minuti. Dopo, le richieste protette rispondono 401: si rifà il login, lo script salva il biglietto nuovo, e le altre richieste lo usano da sole.
Ricorda
- Il login cerca l'utente, controlla la password con
password_giusta, stampa il biglietto concrea_biglietto(utente.username). - Un solo 401, un solo messaggio, per username che non c'è e password sbagliata.
- Il biglietto viaggia nell'header
Authorization: Bearer <biglietto>;HTTPBearer(auto_error=False)lo legge e dàNonese manca. utente_correntefa tre domande: c'è? vale? l'utente esiste ancora? Se no, 401.- Una rotta si protegge con una riga:
utente: UtenteSalvato = Depends(utente_corrente). - Chi sei lo dice il biglietto, mai il corpo o l'indirizzo.
- Sappiamo chi sei. Cosa puoi fare è il prossimo capitoloin arrivo.