Vai al contenuto
code-to-code

Apro l'indice…

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

Login e sicurezza5. Il biglietto: JWTp. 113

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 password

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

Python
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']
3

Una 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 server

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

Python
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, sub ed exp.
  • L'ultima riga fa lo stesso con una riga sola: options={"verify_signature": False} vuol dire «leggi e basta, non controllare niente».
payload = {"sub": "ugo", "exp": 4102444800}payloaddict"sub""ugo""exp"4102444800
Il payload del biglietto di Ugo

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 cambiato

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

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

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

  1. si legge (header e payload sono aperti);
  2. non si cambia (la firma non torna);
  3. 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:

VoceVuol direNel libro
subsubject, il soggetto: chi èlo username, una stringa: "ugo"
expexpiration, quando scadeun 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:

Python
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
1800
  • datetime.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.encode si può dare direttamente il datetime: 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:

HTTP
GET /me HTTP/1.1
Host: 127.0.0.1:8000
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1Z28iLCJleHAiOjQxMDI0NDQ4MDB9.OHxwl-5jMlzd-UzNebrSYUCjg5ZLctPoqmGdedAvJ68

Bearer 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: 1234 si indovina in un attimo);
  • sta in un file .env che 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:

Terminale
python3 -c "import secrets; print('SECRET_KEY=' + secrets.token_hex(32))" > .env
cat .env
SECRET_KEY=dd3d6a2d3b05811ee9941fa99ad70dbf641536c5bca2f3a7d710b66a1022b4ab

secrets.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:

Python
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 .env partendo 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, oppure None se non c'è: niente KeyError.
  • Se manca, raise RuntimeError con una frase chiara. Meglio un programma che non parte e dice perché, di uno che firma biglietti con la chiave None.

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

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

Python
try:
    dati = jwt.decode(biglietto, SECRET_KEY, algorithms=[ALGORITMO])
except jwt.InvalidTokenError:
    ...  # non vale: scaduto, firma sbagliata, non è nemmeno un biglietto

Li proviamo uno per uno, con quattro biglietti: uno buono, uno scaduto da un pezzo, uno firmato con un'altra chiave, uno disegnato a mano.

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

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

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

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

Il 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) ed exp (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 un RuntimeError.
  • jwt.encode(dati, chiave, algorithm=…) crea. jwt.decode(biglietto, chiave, algorithms=[…]) controlla, dentro un try con except jwt.InvalidTokenError.