Il biglietto, JWT, se qualcosa va storto
Gli errori di pyjwt, della chiave e del file .env
Questo capitolo ha più errori degli altri, e hanno tutti un aspetto antipatico: lunghi, in inglese, dentro una libreria. Il trucco è sempre lo stesso: leggi l'ultima riga del traceback, quella con il nome dell'errore. Se non ricordi come si fa, Leggere un traceback lo spiega.
In fondo ai traceback di jwt ci sono righe con site-packages/jwt/…: è la libreria, non il tuo codice. Il tuo codice è la riga che inizia con File "~/Downloads/login-jwt/palestra/…": lì hai chiamato jwt.encode o jwt.decode.
La chiave e il file .env
| Leggi | Vuol dire | Cosa fai |
|---|---|---|
RuntimeError: Manca SECRET_KEY: crea il file .env (README, «Una volta sola») | load_dotenv() non ha trovato il file .env, oppure il file non ha la riga giusta | Controlla con ls -a che il file .env ci sia nella cartella dello zip. Se manca, il comando della chiave nel README |
lo stesso errore, ma il .env c'è | Il file è in un'altra cartella (per esempio dentro un altro zip), oppure si chiama in un altro modo (env.txt, .env.txt: certi editor aggiungono un .txt) | load_dotenv() cerca dalla cartella del file Python verso l'alto: una cartella sorella non la vede. Il nome è esatto: .env, con il punto, senza altro |
lo stesso errore, con .env che contiene solo SECRET_KEY= | La chiave c'è, ma vuota: per il codice è come se mancasse | Rifai il file con il comando del README: la chiave si scrive, non si lascia in bianco |
pytest verde, ma python palestra/stampa_biglietto.py dà RuntimeError: Manca SECRET_KEY | I test usano la chiave dei test (la scrive conftest.py), non il tuo .env: passano anche senza. Il file lanciato a mano ha bisogno del .env | Fai il .env. Non è un errore dei test: è proprio così che sono fatti |
ls non mostra il file .env | I file che cominciano con un punto sono nascosti | ls -a. Nel Finder del Mac: Cmd+Shift+. |
TypeError: Expected a string or bytes value | A jwt.encode (o decode) è arrivata la chiave None: os.environ.get("SECRET_KEY") non ha trovato niente | Il .env c'è? Il nome è scritto esattamente SECRET_KEY? Nel codice vero il blocco in cima si ferma già prima, con il RuntimeError: se lo hai tolto, rimettilo |
InsecureKeyLengthWarning: The HMAC key is 4 bytes long, which is below the minimum recommended length of 32 bytes | Non è un errore: è un avviso. Il biglietto viene fatto, ma con una chiave troppo corta, quindi falsificabile | Chiave nuova, con il comando del README: 64 caratteri, non 4 |
Dopo aver cambiato il .env, i biglietti di prima non valgono più: InvalidSignatureError | La firma si calcola con la chiave: con un'altra chiave non torna. È normale, anzi è la cura giusta se la vecchia è trapelata | Rifai il login e ottieni un biglietto nuovo |
Ecco il primo, come lo vedi:
Traceback (most recent call last):
File "~/Downloads/login-jwt/palestra/stampa_biglietto.py", line 22, 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»)E il TypeError, quando al posto della chiave c'è None (qui SECRET_KEY = os.environ.get("SECRET_KEY") con il file .env mancante, e nessun controllo):
Traceback (most recent call last):
File "~/Downloads/login-jwt/esempi/g2.py", line 7, in <module>
print(jwt.encode({"sub": "ugo", "exp": 4102444800}, SECRET_KEY, algorithm="HS256"))
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "~/Downloads/login-jwt/.venv/lib/python3.12/site-packages/jwt/api_jwt.py", line 149, in encode
return self._jws.encode(
^^^^^^^^^^^^^^^^^
File "~/Downloads/login-jwt/.venv/lib/python3.12/site-packages/jwt/api_jws.py", line 202, in encode
key = alg_obj.prepare_key(key)
^^^^^^^^^^^^^^^^^^^^^^^^
File "~/Downloads/login-jwt/.venv/lib/python3.12/site-packages/jwt/algorithms.py", line 347, in prepare_key
key_bytes = force_bytes(key)
^^^^^^^^^^^^^^^^
File "~/Downloads/login-jwt/.venv/lib/python3.12/site-packages/jwt/utils.py", line 22, in force_bytes
raise TypeError("Expected a string or bytes value")
TypeError: Expected a string or bytes valueLa prima riga File "~/Downloads/login-jwt/…" è la tua: lì hai passato SECRET_KEY a jwt.encode. La causa vera sta più indietro, nel .env che non c'è: la chiave è None.
Gli errori di jwt.decode
| Leggi | Vuol dire | Cosa fai |
|---|---|---|
DecodeError: It is required that you pass in a value for the "algorithms" argument when calling decode(). | jwt.decode vuole sapere con che algoritmo controllare la firma | algorithms=[ALGORITMO], con le quadre: è una lista. Se c'è un try con InvalidTokenError, l'errore non si vede: la funzione dà sempre None (lo trovi come assert None == 'marta') |
DecodeError: Not enough segments | Il testo non ha tre pezzi: non è un biglietto | Controlla cosa stai passando a jwt.decode: è davvero il biglietto, tutto intero? |
DecodeError: Invalid header padding | Il biglietto ha qualcosa davanti: quasi sempre la parola Bearer copiata con il resto | A jwt.decode va solo il biglietto, senza Bearer. Nel capitolo 6 ci pensa il controllore a toglierla |
ExpiredSignatureError: Signature has expired | Il biglietto è scaduto | È la sua natura: se capita nei test, hai fatto un biglietto con minuti negativo o con una scadenza passata. In un programma vero, nuovo login |
InvalidSignatureError: Signature verification failed | La firma non torna: un'altra chiave, o un payload cambiato | Per una prova, sono gli stessi pezzi con la chiave giusta? Se è un test, dovrebbe dare None: serve il try |
InvalidSubjectError: Subject must be a string | Il sub del biglietto è un numero, non una stringa | {"sub": username}: nel libro lo username è una stringa. Con un numero, str(numero) |
jwt.exceptions.… dentro il test, invece di None | Un errore del biglietto esce dalla tua funzione: manca il try, o l'except è troppo stretto | except jwt.InvalidTokenError: la famiglia, non un errore solo |
Il InvalidSubjectError, come lo vedi (le ultime righe):
File "~/Downloads/login-jwt/.venv/lib/python3.12/site-packages/jwt/api_jwt.py", line 421, in _validate_claims
self._validate_sub(payload, subject)
File "~/Downloads/login-jwt/.venv/lib/python3.12/site-packages/jwt/api_jwt.py", line 450, in _validate_sub
raise InvalidSubjectError("Subject must be a string")
jwt.exceptions.InvalidSubjectError: Subject must be a stringIl biglietto con "sub": 7 si crea senza problemi: è alla lettura che la libreria si lamenta. Un errore che esplode lontano da dove l'hai fatto.
E il DecodeError con la parola Bearer davanti:
jwt.exceptions.DecodeError: Invalid header paddingI test della palestra
| Leggi | Vuol dire | Cosa fai |
|---|---|---|
assert None is not None con «crea_biglietto non restituisce niente» | C'è ancora pass, oppure hai scritto print al posto di return | return jwt.encode(…) |
assert None == 'marta' | La funzione ha dato None per un biglietto buono: quasi sempre manca algorithms=[ALGORITMO] | Controlla la prima trappola dell'esercizio 3, nella pagina delle soluzioni |
AttributeError: 'str' object has no attribute 'decode' | Hai attaccato .decode(…) all'uscita di jwt.encode: era per le vecchie versioni, che davano byte | Togli .decode: oggi encode restituisce già una stringa |
assert 3599.26… < 5 sotto «exp deve essere adesso più 30 minuti» | exp è sbagliato di un'ora (3600 secondi) | datetime.now(timezone.utc): con l'UTC, non con l'ora del computer |
assert 1770.9… < 5 | exp è sbagliato di circa 30 minuti, perché i minuti sono diventati secondi | timedelta(minutes=minuti), con minutes |
| «La firma non torna: il biglietto va firmato con SECRET_KEY» | Il biglietto è firmato con una chiave scritta nel codice | jwt.encode(dati, SECRET_KEY, algorithm=ALGORITMO) |
DID NOT RAISE ValueError | La funzione non si è fermata dove doveva | Il controllo dei tre pezzi va prima di jwt.decode |
KeyError: 'SECRET_KEY' | Hai letto la chiave con le quadre, e non c'è | os.environ.get("SECRET_KEY") |
No module named 'jwt' o No module named 'dotenv' | Il venv è spento, oppure pip install -r requirements.txt non è finito | source .venv/bin/activate, da questa cartella, poi pip install -r requirements.txt |
Un dettaglio che confonde: la libreria si installa con pip install pyjwt, ma nel codice si scrive import jwt. E python-dotenv si importa con from dotenv import load_dotenv. Il nome per installare e quello per importare non sono sempre uguali.
Lanciare il file con il Python di sistema invece di quello del venv dà proprio questo, e il venv spento si vede dal prompt, che non comincia con (.venv):
Traceback (most recent call last):
File "<string>", line 1, in <module>
ModuleNotFoundError: No module named 'jwt'Gli errori che non danno errori
Questi non fanno diventare rosso niente, finché non c'è un test apposta.
Il biglietto senza scadenza. Se crea_biglietto dimentica exp, il biglietto si stampa, si legge, funziona. Solo che non scade mai: un biglietto rubato vale per sempre. jwt.decode non lo nota, a meno che non gli chiedi options={"require": ["exp"]}. L'unico modo è un test che guardi exp.
L'ora senza fuso. datetime.now() al posto di datetime.now(timezone.utc): il biglietto dura un'ora in più o in meno, a seconda di dove gira il programma. Sul computer in UTC non si vede: è il primo giorno che il server gira da un'altra parte che qualcosa non torna.
La chiave nel codice. jwt.encode(dati, "segreto", …) funziona benissimo. Anche per chi legge il codice, e per chi lo trova su GitHub: firma biglietti veri per chiunque.
I segreti nel payload. Il payload si legge. Una password, una carta, un numero di telefono nel payload sono pubblici per chiunque abbia il biglietto: basta incollarlo su jwt.io (e, per questo, su jwt.io si incollano solo biglietti di prova).
Se il problema non è il codice
pytest: command not found, No module named pytest, il pannello Testing vuoto: è l'ambiente, non il codice. Ha una pagina sua nel Pronto soccorso: pytest non parte, o non trova niente. Il Pronto soccorso ha anche le voci «Postman e login», per quando il biglietto lo userai dal vivo, nel capitolo 6.