Il biglietto, JWT
Tre pezzi, una firma, una scadenza
- 15 minuti di lettura
Nel capitolo 4 il server ha imparato a riconoscere una password senza conoscerla. Ma riconoscerla costa: argon2 è lento apposta, e la password, a ogni richiesta, viaggerebbe su e giù per la rete. Per un'app che fa dieci richieste al secondo è una follia.
Allora la password si dà una volta sola, al login. In cambio il server consegna un biglietto. Da lì in poi, a ogni richiesta, si mostra il biglietto. In inglese si chiama token: lo dico una volta e poi lo chiamo biglietto, come in metropolitana.
IL LOGIN, UNA VOLTA POI, A OGNI RICHIESTA
app ── username + password ──▶ server app ── il biglietto ──▶ server
app ◀──── il biglietto ─────── server app ◀──── la risposta ── server
la password viaggia una volta sola il server controlla il biglietto, non la passwordIl formato del biglietto si chiama JWT, da JSON Web Token, e si legge «jot». Questo capitolo spiega com'è fatto, perché non si può falsificare e dove si tiene la chiave che lo firma. Come lo consegna il login e come lo controlla la rotta è il capitolo 6: qui il biglietto si crea e si legge con funzioni Python, senza rotte.
Un biglietto vero
Eccone uno. Lo fa la libreria pyjwt (pip install pyjwt: nello zip c'è già nel requirements.txt) per Ugo Pirola, un abbonato della Linea Menta. La chiave qui è finta e scritta nel codice solo per provare: più avanti vedi dove va davvero.
import jwt
CHIAVE = "chiave-finta-solo-per-gli-esempi-del-libro"
biglietto = jwt.encode({"sub": "ugo", "exp": 4102444800}, CHIAVE, algorithm="HS256")
print(biglietto)
print(biglietto.split("."))
print(len(biglietto.split(".")))eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1Z28iLCJleHAiOjQxMDI0NDQ4MDB9.OHxwl-5jMlzd-UzNebrSYUCjg5ZLctPoqmGdedAvJ68
['eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9', 'eyJzdWIiOiJ1Z28iLCJleHAiOjQxMDI0NDQ4MDB9', 'OHxwl-5jMlzd-UzNebrSYUCjg5ZLctPoqmGdedAvJ68']
3Una stringa lunga e senza senso, ma con una regola: tre pezzi separati da due punti. split(".") li taglia, come con l'impronta del capitolo 4.
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9 . eyJzdWIiOiJ1Z28iLCJleHAiOjQxMDI0NDQ4MDB9 . OHxwl-5jMlzd-UzNebrSYUCjg5ZLctPoqmGdedAvJ68
└────────── HEADER ───────────────┘ └─────────────── PAYLOAD ───────────────┘ └──────────── FIRMA ─────────────────┘
come è fatto il biglietto cosa c'è scritto dentro la prova che l'ha fatto il serverSi legge: header e payload
I primi due pezzi non sono cifrati: sono solo codificati (in base64, un modo di scrivere un testo con le sole lettere, i numeri e pochi simboli). Chiunque li legge, senza chiave. Lo vedi con la libreria di Python che li decodifica:
import base64
import jwt
BIGLIETTO = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1Z28iLCJleHAiOjQxMDI0NDQ4MDB9.OHxwl-5jMlzd-UzNebrSYUCjg5ZLctPoqmGdedAvJ68"
header, payload, firma = BIGLIETTO.split(".")
print(base64.urlsafe_b64decode(header))
print(base64.urlsafe_b64decode(payload))
print(jwt.decode(BIGLIETTO, options={"verify_signature": False}))b'{"alg":"HS256","typ":"JWT"}'
b'{"sub":"ugo","exp":4102444800}'
{'sub': 'ugo', 'exp': 4102444800}- Il header dice che firma è stata usata:
HS256, la solita, e che è un JWT. - Il payload (il «carico») è il contenuto: un dizionario. Qui due voci,
subedexp. - L'ultima riga fa lo stesso con una riga sola:
options={"verify_signature": False}vuol dire «leggi e basta, non controllare niente».
Questo è anche quello che fa il sito jwt.io: incolli il biglietto nella casella a sinistra, a destra vedi header e payload già aperti. Serve a curiosare e a capire cosa ti ha dato un login. Ma attenzione: su jwt.io incolla solo biglietti di prova, mai uno vero di un'app che usi.
Non si cambia: la firma
Se chiunque lo legge, chiunque può anche scrivere un payload suo. Cosa impedisce a Teo di prendere il biglietto di Ugo e scrivere «rosa» al posto di «ugo»? La firma, il terzo pezzo.
La firma è un'impronta, come quella delle password, ma fatta con una chiave segreta che conosce solo il server. Il server prende header e payload, ci mescola la chiave, e calcola l'impronta: quella è la firma.
CREARE IL BIGLIETTO
header + payload + la CHIAVE ── calcolo ──▶ firma
│ │ │
└───────┴─────── header . payload . firma ┘
CONTROLLARLO, poi
header + payload + la CHIAVE ── calcolo ──▶ una firma nuova
uguale a quella scritta? sì: lo ha fatto il server
no: è stato cambiatoChi non ha la chiave può cambiare il payload, ma non sa rifare la firma. Proviamo: Teo cambia il payload e lascia la firma di Ugo.
import jwt
CHIAVE = "chiave-finta-solo-per-gli-esempi-del-libro"
BIGLIETTO = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1Z28iLCJleHAiOjQxMDI0NDQ4MDB9.OHxwl-5jMlzd-UzNebrSYUCjg5ZLctPoqmGdedAvJ68"
header, payload, firma = BIGLIETTO.split(".")
altro = jwt.encode({"sub": "rosa", "exp": 4102444800}, "una-chiave-inventata-da-chi-imbroglia", algorithm="HS256")
payload_di_rosa = altro.split(".")[1]
cambiato = f"{header}.{payload_di_rosa}.{firma}"
print(jwt.decode(cambiato, options={"verify_signature": False}))
print(jwt.decode(BIGLIETTO, CHIAVE, algorithms=["HS256"]))
print(jwt.decode(cambiato, CHIAVE, algorithms=["HS256"])){'sub': 'rosa', 'exp': 4102444800}
{'sub': 'ugo', 'exp': 4102444800}
Traceback (most recent call last):
File "~/Downloads/login-jwt/esempi/t3.py", line 13, in <module>
print(jwt.decode(cambiato, CHIAVE, algorithms=["HS256"]))
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "~/Downloads/login-jwt/.venv/lib/python3.12/site-packages/jwt/api_jwt.py", line 370, in decode
decoded = self.decode_complete(
^^^^^^^^^^^^^^^^^^^^^
File "~/Downloads/login-jwt/.venv/lib/python3.12/site-packages/jwt/api_jwt.py", line 267, in decode_complete
decoded = self._jws.decode_complete(
^^^^^^^^^^^^^^^^^^^^^^^^^^
File "~/Downloads/login-jwt/.venv/lib/python3.12/site-packages/jwt/api_jws.py", line 278, in decode_complete
self._verify_signature(
File "~/Downloads/login-jwt/.venv/lib/python3.12/site-packages/jwt/api_jws.py", line 446, in _verify_signature
raise InvalidSignatureError("Signature verification failed")
jwt.exceptions.InvalidSignatureError: Signature verification failedIl biglietto cambiato si legge benissimo («rosa»), ma non vale: la firma non torna, e jwt.decode con la chiave si ferma con InvalidSignatureError. Leggere non è controllare. Per questo, nel server, il biglietto si apre sempre con la chiave: l'opzione «non controllare» è per curiosare, mai per decidere chi entra.
Le tre regole del biglietto, a memoria:
- si legge (header e payload sono aperti);
- non si cambia (la firma non torna);
- scade (lo vediamo adesso).
Cosa c'è dentro: sub ed exp
Il payload del biglietto del libro ha due voci. Hanno nomi fissi, decisi dallo standard JWT:
| Voce | Vuol dire | Nel libro |
|---|---|---|
sub | subject, il soggetto: chi è | lo username, una stringa: "ugo" |
exp | expiration, quando scade | un momento nel futuro: adesso più 30 minuti |
sub deve essere una stringa: con un numero, jwt.decode si ferma. Per questo nel libro è lo username, e non un numero.
exp nel biglietto è un numero: i secondi passati dal 1 gennaio 1970, alle 00:00 in UTC (l'ora di Greenwich, senza ora legale). Un numero così non si legge, ma Python lo traduce:
from datetime import datetime, timedelta, timezone
import jwt
CHIAVE = "chiave-finta-solo-per-gli-esempi-del-libro"
print(datetime.fromtimestamp(4102444800, timezone.utc))
print(datetime.fromtimestamp(1795040100, timezone.utc))
adesso = datetime.now(timezone.utc)
scadenza = adesso + timedelta(minutes=30)
print(scadenza - adesso)
print(int(scadenza.timestamp()) - int(adesso.timestamp()))
biglietto = jwt.encode({"sub": "ugo", "exp": scadenza}, CHIAVE, algorithm="HS256")
dentro = jwt.decode(biglietto, options={"verify_signature": False})
print(dentro["exp"] - int(adesso.timestamp()))2100-01-01 00:00:00+00:00
2026-11-18 22:15:00+00:00
0:30:00
1800
1800datetime.fromtimestamp(numero, timezone.utc)traduce i secondi in una data. Il primo numero è il 1 gennaio 2100: l'ho scelto lontano per gli esempi di questa pagina, perché non scadano mai.datetime.now(timezone.utc)è «adesso», in UTC.timedelta(minutes=30)è una durata. Adesso più 30 minuti è la scadenza.- A
jwt.encodesi può dare direttamente ildatetime: lo trasforma lui in secondi. Nel biglietto ci sono 1800 secondi, cioè 30 minuti, di distanza da adesso.
Chi controlla un biglietto con jwt.decode non deve fare i conti: se exp è già passato, la libreria si ferma da sola con ExpiredSignatureError.
Al portatore
Nelle richieste il biglietto viaggia in un header, con la parola Bearer davanti. Lo vedrai dal vivo nel capitolo 6:
GET /me HTTP/1.1
Host: 127.0.0.1:8000
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1Z28iLCJleHAiOjQxMDI0NDQ4MDB9.OHxwl-5jMlzd-UzNebrSYUCjg5ZLctPoqmGdedAvJ68Bearer vuol dire al portatore, come certi assegni: vale per chi lo porta. Il server non confronta il biglietto con la faccia di nessuno: se la firma torna e non è scaduto, chi lo presenta passa. Chi ruba un biglietto entra al posto tuo, finché dura.
Da qui vengono tre abitudini:
- il biglietto scade presto (30 minuti): un biglietto rubato ha poco tempo;
- il biglietto non si manda in chat, non si incolla su siti, non si stampa nei log;
- il payload non ha segreti, perché si legge.
La chiave: nel .env
La firma vale quanto la chiave. Chi la conosce firma biglietti veri per chiunque: una chiave rubata è un portale aperto. Per questo la chiave:
- non si scrive nel codice (finirebbe su GitHub con tutto il resto);
- è lunga e a caso (almeno 32 caratteri:
1234si indovina in un attimo); - sta in un file
.envche non si carica mai su GitHub.
È la stessa idea della password del database in una variabile d'ambiente, del libro sul database. Il file .env lo hai già visto nel capitolo La chiave: un file di testo con una riga per voce, NOME=valore; la libreria python-dotenv lo legge e mette le voci nell'ambiente (os.environ), da dove Python le prende. La chiave si fa con Python, una volta sola, dalla cartella del progetto:
python3 -c "import secrets; print('SECRET_KEY=' + secrets.token_hex(32))" > .env
cat .envSECRET_KEY=dd3d6a2d3b05811ee9941fa99ad70dbf641536c5bca2f3a7d710b66a1022b4absecrets.token_hex(32) tira fuori 32 byte a caso, scritti come 64 caratteri: più che sufficienti. Il > mette l'output nel file .env invece di stamparlo. La tua chiave sarà diversa, e non si copia da nessuna parte. Nemmeno quella che vedi qui: ormai la conosce chiunque legga la pagina.
Il file .env comincia con un punto, quindi ls non lo mostra. Con ls -a sì (nel Finder del Mac: Cmd+Shift+.). Nello zip trovi anche .env.example: il modello, con una chiave finta, che si può caricare su GitHub; il .gitignore dello zip contiene la riga .env, perché quello vero non parta mai.
Poi il codice la prende così, e si ferma se non la trova:
import os
from dotenv import load_dotenv
load_dotenv()
SECRET_KEY = os.environ.get("SECRET_KEY")
if not SECRET_KEY:
raise RuntimeError("Manca SECRET_KEY: crea il file .env (README, «Una volta sola»)")
ALGORITMO = "HS256"load_dotenv()cerca il file.envpartendo dalla cartella del file Python e salendo verso quelle sopra, e ne copia le voci nell'ambiente. Se una voce c'è già, non la cambia.os.environ.get("SECRET_KEY")dà la chiave, oppureNonese non c'è: nienteKeyError.- Se manca,
raise RuntimeErrorcon una frase chiara. Meglio un programma che non parte e dice perché, di uno che firma biglietti con la chiaveNone.
Senza il file .env, un lancio dice questo:
Traceback (most recent call last):
File "~/Downloads/login-jwt/palestra/prova_chiave.py", line 9, in <module>
raise RuntimeError("Manca SECRET_KEY: crea il file .env (README, «Una volta sola»)")
RuntimeError: Manca SECRET_KEY: crea il file .env (README, «Una volta sola»)ALGORITMO = "HS256" è l'algoritmo della firma: HMAC con sha256, quello con una chiave sola, che serve a firmare e a controllare. Lo scriviamo in una costante, perché serve in due posti.
Creare il biglietto: jwt.encode
scadenza = datetime.now(timezone.utc) + timedelta(minutes=30)
dati = {"sub": username, "exp": scadenza}
biglietto = jwt.encode(dati, SECRET_KEY, algorithm=ALGORITMO)Tre argomenti: il payload (un dizionario), la chiave, l'algoritmo. Restituisce il biglietto, già una stringa.
Leggerlo davvero: jwt.decode
Il contrario: dal biglietto, il payload, se vale. Qui l'argomento in più è algorithms, una lista (le quadre!) di algoritmi accettati: serve a dire «mi fido solo di HS256». Se il biglietto non vale, la libreria alza un errore. Gli errori sono tanti, ma di una stessa famiglia: jwt.InvalidTokenError. Un solo except li prende tutti, come nel capitolo su try ed except:
try:
dati = jwt.decode(biglietto, SECRET_KEY, algorithms=[ALGORITMO])
except jwt.InvalidTokenError:
... # non vale: scaduto, firma sbagliata, non è nemmeno un bigliettoLi proviamo uno per uno, con quattro biglietti: uno buono, uno scaduto da un pezzo, uno firmato con un'altra chiave, uno disegnato a mano.
import jwt
CHIAVE = "chiave-finta-solo-per-gli-esempi-del-libro"
VALIDO = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1Z28iLCJleHAiOjQxMDI0NDQ4MDB9.OHxwl-5jMlzd-UzNebrSYUCjg5ZLctPoqmGdedAvJ68"
SCADUTO = jwt.encode({"sub": "ugo", "exp": 1795040100}, CHIAVE, algorithm="HS256")
ALTRA_CHIAVE = jwt.encode({"sub": "ugo", "exp": 4102444800}, "una-chiave-inventata-da-chi-imbroglia", algorithm="HS256")
for nome, biglietto in [
("valido", VALIDO),
("scaduto", SCADUTO),
("altra chiave", ALTRA_CHIAVE),
("disegnato a mano", "biglietto-disegnato-a-mano"),
]:
try:
dentro = jwt.decode(biglietto, CHIAVE, algorithms=["HS256"])
print(f"{nome}: vale, sub = {dentro['sub']}")
except jwt.InvalidTokenError as errore:
print(f"{nome}: non vale, {type(errore).__name__}: {errore}")valido: vale, sub = ugo
scaduto: non vale, ExpiredSignatureError: Signature has expired
altra chiave: non vale, InvalidSignatureError: Signature verification failed
disegnato a mano: non vale, DecodeError: Not enough segmentsTre errori diversi, tutti della famiglia InvalidTokenError: scaduto (ExpiredSignatureError), firma che non torna (InvalidSignatureError: l'altra chiave, o il payload cambiato), non è nemmeno un biglietto (DecodeError). Un except solo li prende tutti.
Mettiamo insieme: due funzioni
Il punto d'arrivo del capitolo sono due funzioni. Le scrivi tu nella palestra; nel capitolo 6 le trovi già pronte in sicurezza.py, e ti basta usarle.
def crea_biglietto(username: str, minuti: int = 30) -> str:
scadenza = datetime.now(timezone.utc) + timedelta(minutes=minuti)
dati = {"sub": username, "exp": scadenza}
return jwt.encode(dati, SECRET_KEY, algorithm=ALGORITMO)
def leggi_biglietto(biglietto: str) -> str | None:
try:
dati = jwt.decode(biglietto, SECRET_KEY, algorithms=[ALGORITMO])
except jwt.InvalidTokenError:
return None
return dati.get("sub")crea_biglietto mette dentro chi è e quando scade. leggi_biglietto restituisce lo username, oppure None se il biglietto non vale: chi chiama vuole sapere solo «chi è?», e None vuol dire «nessuno». Provate con la chiave del .env:
biglietto = crea_biglietto("ugo")
print(biglietto)
print(leggi_biglietto(biglietto))
print(leggi_biglietto(biglietto + "x"))
print(leggi_biglietto(crea_biglietto("ugo", minuti=-1)))
print(leggi_biglietto("biglietto-disegnato-a-mano"))eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1Z28iLCJleHAiOjE3OTUxMTMyMjd9.YoonKPYaZxUWT4z20SvNjL8znGUP7O2kICfCkAKVXc8
ugo
None
None
NoneIl tuo biglietto sarà diverso: dentro ci sono la tua chiave e l'ora in cui lo fai. Il secondo risultato è ugo. Gli altri tre sono None: una lettera in più nella firma, un biglietto già scaduto (minuti=-1: scaduto da un minuto), un biglietto disegnato a mano.
Ricorda
- La password si dà una volta sola, al login. Poi si mostra il biglietto, un JWT: tre pezzi separati da due punti, header, payload, firma.
- Header e payload si leggono (jwt.io, o
options={"verify_signature": False}): niente segreti dentro, mai. La firma non si rifà senza la chiave: un payload cambiato non vale. - Nel payload:
sub(chi è, una stringa) edexp(quando scade, in secondi, in UTC). Il biglietto è al portatore: chi lo ruba entra finché dura. - La chiave sta nel
.env: a caso, almeno 32 caratteri, mai nel codice, mai su GitHub. Se manca, il programma si ferma con unRuntimeError. jwt.encode(dati, chiave, algorithm=…)crea.jwt.decode(biglietto, chiave, algorithms=[…])controlla, dentro untryconexcept jwt.InvalidTokenError.