Vai al contenuto
code-to-code

Apro l'indice…

↑ ↓ per scegliere, Invio per aprire, Esc per chiudere

Login e sicurezza6. Login e rotte protettep. 143

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:

  1. il login: una rotta che prende username e password e restituisce il biglietto;
  2. il controllore: una funzione che a ogni richiesta guarda il biglietto e dice chi sei;
  3. 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 parte

Il 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.

Python
@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:

  1. utenti.get(dati.username): l'utente, oppure None se lo username non c'è. Con le quadre sarebbe un KeyError, cioè un 500.
  2. utente is None or not password_giusta(...): un solo if per due guai. Lo username non c'è? Oppure c'è ma la password non è la sua? Il risultato è lo stesso: 401. Se utente è None, Python si ferma al primo pezzo dell'or e non guarda nemmeno la password.
  3. 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:

Terminale
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:

HTTP
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:

Python
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 richiestaCosa riceve la tua funzione
Authorization: Bearer eyJabc.def.ghiun oggetto con scheme uguale a "Bearer" e credentials uguale a "eyJabc.def.ghi"
nessun headerNone
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:

header = HTTPAuthorizationCredentials(scheme="Bearer", credentials="eyJabc.def.ghi")headerHTTPAuthorizationCredentialsscheme"Bearer"credentials"eyJabc.def.ghi"
L'header con il biglietto

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'headerX-API-Key: …, letto con Header(default=None, alias="X-API-Key")Authorization: Bearer …, letto da controllore (HTTPBearer) con Depends(controllore)
2. Il confrontochiave != CHIAVE_MAGAZZINO: è uguale alla copia nel .env?leggi_biglietto(header.credentials): la firma torna, non è scaduto?
3. Chi seila chiave dice solo quale programma: "Valdora Ricambi"il biglietto porta lo username: utenti.get(username) cerca l'utente
4. Il returnil nome del fornitorel'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:

Python
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 utente

Tre domande, nell'ordine:

  1. C'è un biglietto? Se header è None: 401, «Manca il biglietto». Senza questa riga, il passo dopo scrive header.credentials su un None e il server risponde 500.
  2. Il biglietto vale? leggi_biglietto (la scrivi nel capitolo 5, qui è già pronta) controlla firma e scadenza e restituisce lo username, oppure None.
  3. Quell'utente esiste ancora? utenti.get(username). Con username uguale a None il get dà None e basta, senza errori: così le domande 2 e 3 finiscono nello stesso if, 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.

Python
@app.get("/me")
def chi_sono(utente: UtenteSalvato = Depends(utente_corrente)) -> Utente:
    return utente

Il 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.

Terminale
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 giusto

Tutti 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.

Python
@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:

  1. Nella collezione, la variabile baseUrl vale http://127.0.0.1:8000.
  2. Richiesta POST a {{baseUrl}}/login. Body → raw → JSON, con {"username": "lucia", "password": "capotreno-M12"}.
  3. Nella scheda Scripts → Post-response, questa riga, che prende access_token dalla risposta e lo salva nella variabile biglietto:
javascript
pm.collectionVariables.set("biglietto", pm.response.json().access_token);
  1. Nelle richieste protette: Authorization → Auth Type → Bearer Token → {{biglietto}}. Postman scrive da solo l'header Authorization: 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 con crea_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à None se manca.
  • utente_corrente fa 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.