Chi sei, cosa puoi fare
Due domande diverse, tre codici da non confondere
- 10 minuti di lettura
Le API che hai scritto finora rispondono a tutti allo stesso modo. Chi chiede GET /treni/M12 riceve il treno M12, chiunque sia.
Per tante cose va bene: gli orari della Linea Menta li può leggere chiunque. Ma la tessera dell'abbonamento di Teo Galbiati no: quella è sua. Prima di scrivere una riga di login, servono due parole e tre numeri.
Due domande diverse
In stazione, a Porta Codice, ti possono fermare per due motivi diversi.
- Non hai il biglietto. Il tornello non sa chi sei, e non ti fa passare.
- Hai il biglietto, ma provi la porta «solo personale». Il biglietto è buono: chi sei si sa. Ma quella porta non è per te.
Sono due domande diverse, e hanno due nomi:
| La domanda | Si chiama | Se la risposta è no |
|---|---|---|
| Chi sei? | autenticazione | 401 Unauthorized |
| Cosa puoi fare? | autorizzazione | 403 Forbidden |
Autenticazione vuol dire dimostrare chi sei. Lo dimostri una volta, con username e password: è il login. In cambio ricevi un biglietto, e da lì in poi lo mostri a ogni richiesta.
Autorizzazione vuol dire decidere, sapendo già chi sei, se una cosa la puoi fare.
Le due parole si somigliano. Un trucco per tenerle distinte: autenticazione, «sei autentico?», sei davvero tu? Autorizzazione, «chi ti autorizza?», hai il permesso?
Il terzo codice: 404
C'è un terzo motivo per cui ti fermano: chiedi una cosa che non c'è. Il binario 9 di Porta Codice non esiste. Puoi avere il biglietto più valido del mondo, ma lì non ci arrivi.
404 Not Found lo conosci già: è il get che risponde None, nel capitolo CRUD su un dizionario. Da solo non c'entra con il login. Ma in una rotta protetta il 404 sta in mezzo alle altre due domande, e l'ordine conta.
Il disegno
Teo chiede la tessera A-101. Il server si fa tre domande, sempre in quest'ordine:
GET /tessere/A-101
Authorization: Bearer <il biglietto di Teo>
│
▼
┌─────────────────────────────────────┐
1. │ CHI SEI? ├── non lo so ──▶ 401 Unauthorized
│ c'è un biglietto, e vale? │
└────────────────────┬────────────────┘
│ sì: sei Teo
▼
┌─────────────────────────────────────┐
2. │ LA COSA C'È? ├── no ─────────▶ 404 Not Found
│ la tessera A-101 esiste? │
└────────────────────┬────────────────┘
│ sì: è di Rosa
▼
┌─────────────────────────────────────┐
3. │ PUOI? ├── no ─────────▶ 403 Forbidden
│ la tessera è tua? │
└────────────────────┬────────────────┘
│ sì
▼
200 OKLa prima domanda a cui la risposta è «no» decide il codice, e il server si ferma lì. Se la risposta è «sì» a tutte e tre, la rotta fa il suo lavoro. Qui la tessera A-101 è di Rosa Bellini: Teo riceve 403.
I tre codici
| Codice | Vuol dire | Sulla Linea Menta | Cosa fa chi lo riceve |
|---|---|---|---|
401 Unauthorized | Non so chi sei: il biglietto manca, oppure non vale (scaduto, falso) | Il tornello, senza biglietto | Fa il login, o lo rifà, e riprova con il biglietto nuovo |
403 Forbidden | So chi sei, ma questo non lo puoi fare | La porta «solo personale», con un biglietto da passeggero | Rifare il login non serve: chi sei si sa già. Serve un permesso, e lo dà una persona |
404 Not Found | Quello che chiedi non c'è | Il binario 9 di Porta Codice | Controlla l'indirizzo: la cosa non c'è, o non c'è più |
Com'è fatta una richiesta protetta
Una richiesta protetta porta due informazioni, in due posti diversi:
GET /tessere/A-205 HTTP/1.1
Host: 127.0.0.1:8000
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ0ZW8iLCJleHAiOjE3OTUxMTMxNDV9.g0nzbW3W…- Il percorso dice cosa chiedi: la tessera A-205.
- L'header
Authorizationdice chi sei: dopo la parolaBearerc'è il biglietto di Teo (qui accorciato: è lungo). - Cosa puoi fare non lo dice nessuno dei due. Lo decide il server, con le sue regole.
Gli header li conosci dal capitolo Il viaggio di una richiesta. Chi sei lo dice sempre il biglietto: mai il percorso, mai il corpo. /tessere/A-205 vuol dire «voglio la tessera A-205», non «sono Teo».
Le risposte vere
Questa è l'app degli abbonati della Linea Menta, accesa davvero. Il suo codice lo scriverai nei prossimi capitoli: qui guardiamo solo cosa risponde. Teo Galbiati, tessera A-205, manda sei richieste:
| # | La richiesta | Per il server |
|---|---|---|
| 1 | GET /tessere/A-205, senza biglietto | uno sconosciuto |
| 2 | POST /login, con username e password di Teo | qualcuno che dimostra di essere Teo |
| 3 | GET /tessere/A-205, con il biglietto | Teo, e la tessera è sua |
| 4 | GET /tessere/A-101, con il biglietto | Teo, ma la tessera è di Rosa |
| 5 | GET /tessere/A-999, con il biglietto | Teo, e la tessera non esiste |
| 6 | GET /tessere/A-999, senza biglietto | di nuovo uno sconosciuto |
Il server, nel terminale di fastapi dev, scrive una riga per ogni richiesta. Il codice è in fondo alla riga:
INFO: 127.0.0.1:63126 - "GET /tessere/A-205 HTTP/1.1" 401 Unauthorized
INFO: 127.0.0.1:63127 - "POST /login HTTP/1.1" 200 OK
INFO: 127.0.0.1:63128 - "GET /tessere/A-205 HTTP/1.1" 200 OK
INFO: 127.0.0.1:63129 - "GET /tessere/A-101 HTTP/1.1" 403 Forbidden
INFO: 127.0.0.1:63130 - "GET /tessere/A-999 HTTP/1.1" 404 Not Found
INFO: 127.0.0.1:63131 - "GET /tessere/A-999 HTTP/1.1" 401 UnauthorizedGuarda la prima riga e l'ultima: senza biglietto, la risposta è 401 sia per la tessera che c'è sia per quella che non c'è. Le richieste una per una, con le risposte intere, sono negli esercizi spiegati.
Perché quest'ordine
Prima: chi sei? A chi non conosciamo non diciamo niente, nemmeno se la cosa che cerca esiste. Se uno sconosciuto ricevesse 404 per A-999 e 401 per A-101, avrebbe appena scoperto quali tessere esistono.
Poi: la cosa c'è? Per sapere se la tessera è tua, il server la deve leggere: c'è scritto sopra di chi è. Se la tessera non c'è, non c'è niente da leggere: 404.
Per ultimo: puoi? Solo adesso il server ha tutti e due i pezzi: chi sei, dal biglietto, e di chi è la tessera, dalla tessera. Li confronta: se non tornano, 403.
Il login sbagliato: sempre 401
Il login è la porta dove dimostri chi sei. Se qualcosa non torna, la risposta è sempre 401, con lo stesso messaggio:
| Ugo Pirola sbaglia… | Codice | Messaggio |
|---|---|---|
| la password | 401 | Username o password sbagliati |
lo username: ugo.pirola non esiste, il suo è ugo | 401, non 404 | Username o password sbagliati |
Perché non 404, se lo username non c'è? Perché chiunque potrebbe provare dei nomi e guardare quali danno 404: scoprirebbe chi è iscritto. Con la stessa risposta e lo stesso messaggio, chi prova a indovinare non impara niente.
Nel codice: tre raise
I tre codici, in FastAPI, sono i raise HTTPException che conosci dal libro HTTP:
raise HTTPException(status_code=401, detail="Manca il biglietto") # chi sei? non lo so
raise HTTPException(status_code=404, detail="Tessera non trovata") # la tessera c'è? no
raise HTTPException(status_code=403, detail="Questa tessera non è tua") # puoi? noIl 404 lo sai già scrivere. Il 401 lo scrivi nel capitolo 6, dentro il controllore che legge il biglietto. Il 403 arriva nel capitolo 7, con i permessi.
Il quadro del libro
Tutto il libro, in un disegno. La password si manda una volta sola; poi gira il biglietto. Prima, nei capitoli 2 e 3, la porta più semplice: una chiave fissa nell'header, quella dei programmi che parlano con altri programmi, e il controllore che le fa la guardia.
IL CLIENT IL SERVER
1. POST /login ──────────▶ cerca l'utente, controlla la password cap. 4
username e password (salvata come impronta, mai in chiaro)
◀────────── il biglietto, firmato, che scade cap. 5
oppure 401
2. GET /tessere/A-205 ──────────▶ il controllore legge il biglietto cap. 6
Authorization: Bearer … chi sei? la cosa c'è? puoi?
◀────────── 200, oppure 401, 404, 403 cap. 1 e 7
3. un'altra richiesta, con lo stesso biglietto, finché non scadeIl capitolo 2 è La chiave, il 3 Depends, da zero, il 4 Le password, il 5 Il biglietto: JWT, il 6 Login e rotte protette.
Ricorda
- Autenticazione: chi sei? Se non lo so, 401.
- Autorizzazione: cosa puoi fare? Se non puoi, 403.
- 401 Unauthorized vuol dire «non so chi sei», nonostante il nome.
- L'ordine: chi sei (401), la cosa c'è (404), puoi (403). La prima risposta «no» decide.
- Al login, username o password sbagliati: sempre 401, sempre lo stesso messaggio.