Vai al contenuto
code-to-code

Apro l'indice…

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

Login e sicurezza2. La chiave: API Keyp. 33

La chiave, esercizi spiegati

Cinque esempi, dalla chiave al fornitore che la perde

  • 30 minuti di lettura

Cinque esempi, dal più semplice. Dentro ci sono gli stessi pezzi della teoria: la chiave, il .env, l'header, il controllore. Ognuno ha lo stesso ritmo:

  1. Prevedi: leggi il codice e scrivi su un foglio cosa risponde. Prima di aprire la risposta.
  2. In italiano: cosa fa il programma, a parole.
  3. Passo per passo: cosa succede a ogni richiesta.
  4. Cosa portiamo a casa: la cosa da ricordare.

Per provarli: una cartella nuova per ogni esempio, con il venv acceso e pip install "fastapi[standard]" httpx python-dotenv. Il codice lo salvi in un file; il server si accende con fastapi dev nome_del_file.py e le richieste si lanciano da un secondo terminale con curl. Le chiavi che vedrai tu saranno diverse da queste: la tua si fa con secrets, e non si copia.


A · Fare la chiave, metterla nel .env

Il tabellone di Piazza Query chiederà i ritardi al server della Linea Menta, e il server gli deve dare una chiave. Prima di tutto, la chiave. Poi il posto dove tenerla.

Terminale
python3 -c "import secrets; print(secrets.token_bytes(16))"
python3 -c "import secrets; print(secrets.token_bytes(16).hex())"
python3 -c "import secrets; print(secrets.token_hex(16))"
python3 -c "import secrets; print(len(secrets.token_hex(16)))"
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
b'\x8e\x11\xe6\xf7y5\x05"\xd4\x85\x9d\x01@Mfa'
6c29d3bd3af684114b2630bb9fcd6bd1
e827e537567ccb05485c02f331af8f17
32

Ogni riga è diversa dalle altre, e la tua sarà diversa da queste. La prima sono 16 byte grezzi: non si possono scrivere in un file di testo. La seconda li scrive in esadecimale (.hex()): 2 caratteri per byte. La terza fa le due cose insieme. La quarta conta: 32 caratteri.

Adesso la chiave va nel file .env, con il suo nome, e Python la legge da lì:

Terminale
python3 -c "import secrets; print('CHIAVE_RITARDI=' + secrets.token_hex(16))" > .env
ls
ls -a
cat .env
Python
import os

from dotenv import load_dotenv

print(os.environ.get("CHIAVE_RITARDI"))
load_dotenv()
print(os.environ.get("CHIAVE_RITARDI"))
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
(il primo ls non mostra niente)
.
..
.env
CHIAVE_RITARDI=8e208e36d1e875e4c6257437675fbd31

E il programma:

None
8e208e36d1e875e4c6257437675fbd31

ls non mostra il file, perché comincia con un punto: ls -a sì. E la chiave arriva nell'ambiente solo dopo load_dotenv(): prima, os.environ.get dà None.

In italiano.

  1. secrets tira fuori byte a caso, e token_hex(16) li scrive come 32 caratteri leggibili.
  2. Il comando di terminale ci attacca davanti CHIAVE_RITARDI= e scrive la riga nel file .env (il >).
  3. Il programma Python, all'inizio, non sa niente della chiave. load_dotenv() apre il .env e copia le sue righe nell'ambiente.
  4. Da quel momento os.environ.get("CHIAVE_RITARDI") dà la chiave.

Passo per passo.

RigaCosa succedeCosa c'è in os.environ
print(os.environ.get("CHIAVE_RITARDI"))niente è stato caricatoCHIAVE_RITARDI non c'è: None
load_dotenv()legge il .env, riga per rigaora CHIAVE_RITARDI c'è
print(os.environ.get("CHIAVE_RITARDI"))la variabile c'èla chiave

Cosa portiamo a casa. La chiave si fa con secrets e si tiene nel .env, non nel codice. Il codice dice solo come si chiama la variabile; il valore sta nel file che resta sul tuo computer.


B · Cosa arriva al parametro

Prima di scrivere il controllore, guardiamo cosa riceve un parametro letto dall'header. Un'API di prova ha tre rotte, che si limitano a rimandare indietro quello che ricevono. Cambia solo la riga del parametro.

Python
from fastapi import FastAPI, Header

app = FastAPI(title="Cosa arriva al parametro")


@app.get("/con-default")
def con_default(chiave: str | None = Header(default=None, alias="X-API-Key")) -> dict:
    return {"chiave": chiave}


@app.get("/senza-default")
def senza_default(chiave: str = Header(alias="X-API-Key")) -> dict:
    return {"chiave": chiave}


@app.get("/senza-alias")
def senza_alias(chiave: str | None = Header(default=None)) -> dict:
    return {"chiave": chiave}

Quattro richieste, per ognuna delle tre rotte: con X-API-Key: abc123; senza header; con un header che si chiama chiave: abc123; con l'header X-API-Key presente ma vuoto.

Terminale
curl -s -w "  → %{http_code}\n" http://127.0.0.1:8000/con-default -H "X-API-Key: abc123"
curl -s -w "  → %{http_code}\n" http://127.0.0.1:8000/con-default
curl -s -w "  → %{http_code}\n" http://127.0.0.1:8000/con-default -H "chiave: abc123"
curl -s -w "  → %{http_code}\n" http://127.0.0.1:8000/con-default -H "X-API-Key;"

(-H "X-API-Key;", con il punto e virgola, è il modo di curl per mandare un header vuoto.) E lo stesso per /senza-default e /senza-alias.

Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.

/con-default:

{"chiave":"abc123"}  → 200
{"chiave":null}  → 200
{"chiave":null}  → 200
{"chiave":""}  → 200

/senza-default:

{"chiave":"abc123"}  → 200
{"detail":[{"type":"missing","loc":["header","X-API-Key"],"msg":"Field required","input":null}]}  → 422
{"detail":[{"type":"missing","loc":["header","X-API-Key"],"msg":"Field required","input":null}]}  → 422
{"chiave":""}  → 200

/senza-alias:

{"chiave":null}  → 200
{"chiave":null}  → 200
{"chiave":"abc123"}  → 200
{"chiave":null}  → 200

Tre cose da guardare. Su /senza-default, senza header: 422, e il corpo è l'errore di FastAPI, non un tuo messaggio. Su /senza-alias, la chiave arriva solo con l'header che si chiama chiave: senza alias il nome dell'header è quello del parametro. E con l'header vuoto chiave non è None: è la stringa vuota "".

In italiano. FastAPI guarda il parametro. Header(…) gli dice di cercare tra gli header. Il nome che cerca è l'alias, se c'è; altrimenti il nome del parametro. Se l'header non c'è, usa il default; se non c'è nemmeno quello, la richiesta è incompleta e risponde 422 da solo.

Passo per passo.

RottaX-API-Key: abc123nessun headerchiave: abc123X-API-Key vuoto
/con-default"abc123"NoneNone""
/senza-default"abc123"422422""
/senza-aliasNoneNone"abc123"None

Cosa portiamo a casa. default=None e alias="X-API-Key" servono tutti e due. Senza il primo, il tuo 401 non esce mai (esce un 422). Senza il secondo, il parametro cerca un header che nessuno manda. E None e "" sono due cose diverse: un header vuoto c'è, solo che non dice niente.


C · Il controllore del tabellone

Ora il controllore vero. Il server della Linea Menta dà i ritardi dei treni, e li apre solo al tabellone di Piazza Query, che ha la sua chiave nel .env.

Python
import os

from dotenv import load_dotenv
from fastapi import Depends, FastAPI, Header, HTTPException

load_dotenv()
CHIAVE_RITARDI = os.environ["CHIAVE_RITARDI"]

RITARDI = {"M12": 4, "M14": 0, "M16": 11}

app = FastAPI(title="I ritardi della Linea Menta")


def controlla_chiave(chiave: str | None = Header(default=None, alias="X-API-Key")) -> str:
    if chiave is None:
        raise HTTPException(status_code=401, detail="Manca la chiave")
    if chiave != CHIAVE_RITARDI:
        raise HTTPException(status_code=401, detail="Chiave sbagliata")
    return "Tabellone di Piazza Query"


@app.get("/ritardi")
def leggi_ritardi(cliente: str = Depends(controlla_chiave)) -> dict:
    return {"cliente": cliente, "ritardi": RITARDI}

Nel .env: CHIAVE_RITARDI=e41b7c09d2a65f38b0c1947ad6e25f83. Cinque richieste: senza header; con l'header vuoto; con la chiave giusta meno l'ultimo carattere; con la chiave giusta; con la chiave giusta tutta in maiuscolo.

Terminale
curl -s -w "  → %{http_code}\n" http://127.0.0.1:8000/ritardi
curl -s -w "  → %{http_code}\n" http://127.0.0.1:8000/ritardi -H "X-API-Key;"
curl -s -w "  → %{http_code}\n" http://127.0.0.1:8000/ritardi -H "X-API-Key: e41b7c09d2a65f38b0c1947ad6e25f8"
curl -s -w "  → %{http_code}\n" http://127.0.0.1:8000/ritardi -H "X-API-Key: e41b7c09d2a65f38b0c1947ad6e25f83"
curl -s -w "  → %{http_code}\n" http://127.0.0.1:8000/ritardi -H "X-API-Key: E41B7C09D2A65F38B0C1947AD6E25F83"
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
{"detail":"Manca la chiave"}  → 401
{"detail":"Chiave sbagliata"}  → 401
{"detail":"Chiave sbagliata"}  → 401
{"cliente":"Tabellone di Piazza Query","ritardi":{"M12":4,"M14":0,"M16":11}}  → 200
{"detail":"Chiave sbagliata"}  → 401

Solo la quarta passa. Le due chiavi quasi giuste (una lettera in meno, tutto in maiuscolo) sono sbagliate come quella a caso: un confronto con != è esatto. E l'header vuoto non è «mancante»: è una chiave sbagliata.

inizio GET /ritardi chiave = valore dell'header X-API-Key se chiave is None sì: errore 401 Manca la chiave se chiave != CHIAVE_RITARDI sì: errore 401 Chiave sbagliata restituisci il nome del cliente, e la rotta parteGET /ritardichiave = valore dell'headerX-API-Keychiave is None401 Manca la chiavechiave !=CHIAVE_RITARDI401 Chiave sbagliatarestituisci il nome delcliente, e la rotta partenosìnosì
Il controllore del tabellone

In italiano. Prima dell'if, FastAPI ha già letto l'header e messo il suo valore in chiave. Il controllore fa due domande: c'è? è quella giusta? Se una risposta è «no», si ferma con il suo 401. Se passa, restituisce il nome del cliente, e quel nome arriva nel parametro cliente della rotta.

Passo per passo.

Richiestachiavechiave is Nonechiave != CHIAVE_RITARDIRisposta
nessun headerNonesìnon si guarda401 Manca la chiave
header vuoto""nosì401 Chiave sbagliata
una lettera in meno"e41b…25f8"nosì401 Chiave sbagliata
quella giusta"e41b…25f83"nono200, cliente vale "Tabellone di Piazza Query"
tutta in maiuscolo"E41B…25F83"nosì401 Chiave sbagliata

Cosa portiamo a casa. Il controllore è una funzione che o ferma (raise) o consegna (return). Le due domande vanno in questo ordine: se non guardi prima None, il confronto con la chiave giusta ti dà un 401 sbagliato per un header che non c'era.


D · Il programma che chiama

Adesso dall'altra parte. Valdora Ricambi ha un programma che ogni notte legge le scorte dal server del magazzino (quello della teoria, acceso). La chiave gliel'ha data il magazzino, a mano: Valdora l'ha messa nel suo .env.

Python
import os

import httpx
from dotenv import load_dotenv

load_dotenv()
CHIAVE = os.environ["CHIAVE_MAGAZZINO"]

risposta = httpx.get("http://127.0.0.1:8000/magazzino", headers={"X-API-Key": CHIAVE})
print(risposta.status_code)
print(risposta.json())

Tre notti. La prima, con la chiave giusta nel .env. La seconda, con una chiave sbagliata (un carattere cambiato). La terza, senza il file .env.

Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
200
{'fornitore': 'Valdora Ricambi', 'scorte': {'guarnizione-P12': 140, 'fusibile-F5': 62, 'faro-led-M': 9}}
401
{'detail': 'Chiave sbagliata'}
Traceback (most recent call last):
  File "~/fornitore/fornitore.py", line 7, in <module>
    CHIAVE = os.environ["CHIAVE_MAGAZZINO"]
             ~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^
  File "<frozen os>", line 714, in __getitem__
KeyError: 'CHIAVE_MAGAZZINO'

Nella terza il programma non arriva nemmeno a chiamare il server: si ferma alla riga 7, perché la variabile non c'è. Nella seconda, invece, il programma gira bene e chi dice no è il server: il programma stampa il suo 401. (Il percorso del file, nel traceback, sarà quello del tuo computer.)

In italiano.

  1. load_dotenv() carica il .env di Valdora nell'ambiente.
  2. os.environ["CHIAVE_MAGAZZINO"] prende la chiave, con le quadre: se manca, il programma si ferma qui con un KeyError.
  3. httpx.get(…) manda la richiesta. headers= è un dizionario: la chiave sta nell'header X-API-Key, non nell'indirizzo.
  4. risposta.status_code è il codice, risposta.json() il corpo come dizionario Python.

Passo per passo.

NotteIl .env di ValdoraCosa manda il programmaCosa risponde il server
primala chiave giustaX-API-Key: 6085…200 e le scorte
secondauna chiave diversaX-API-Key: 6085…b401 Chiave sbagliata
terzanon c'èniente: il programma si ferma primaniente

Cosa portiamo a casa. Il client mette la chiave nell'header, e la prende dall'ambiente, non dal codice. E il 401 che stampa il programma è la risposta del server: leggilo, perché dice «Manca» o «sbagliata».


E · Una chiave per impresa, e una chiave persa

Il calendario delle pulizie dei treni lo leggono tre imprese, ognuna con la sua chiave. L'elenco è un dizionario chiave → impresa.

Python
from fastapi import Depends, FastAPI, Header, HTTPException

# chiave -> impresa. Chiavi finte, per imparare: in un programma vero stanno nel .env o nel database.
CHIAVI = {
    "chiave-lucente-3f9a": "Pulizie Lucente",
    "chiave-rapida-b71c": "Nettezza Rapida",
    "chiave-argento-52de": "Argento Servizi",
}

TURNI = {"M12": "notte", "M14": "mattina", "M16": "notte"}

app = FastAPI(title="Il calendario delle pulizie")


def controlla_chiave(chiave: str | None = Header(default=None, alias="X-API-Key")) -> str:
    if chiave is None:
        raise HTTPException(status_code=401, detail="Manca la chiave")
    impresa = CHIAVI.get(chiave)
    if impresa is None:
        raise HTTPException(status_code=401, detail="Chiave sbagliata")
    return impresa


@app.get("/pulizie")
def leggi_pulizie(impresa: str = Depends(controlla_chiave)) -> dict:
    return {"impresa": impresa, "turni": TURNI}

Nettezza Rapida perde la sua chiave: la lascia su un sedile di un treno. Il magazzino la toglie dall'elenco (cancella la riga "chiave-rapida-b71c": …) e il server riparte. Le tre richieste, con le tre chiavi, prima e dopo:

Terminale
curl -s -w "  → %{http_code}\n" http://127.0.0.1:8000/pulizie -H "X-API-Key: chiave-lucente-3f9a"
curl -s -w "  → %{http_code}\n" http://127.0.0.1:8000/pulizie -H "X-API-Key: chiave-rapida-b71c"
curl -s -w "  → %{http_code}\n" http://127.0.0.1:8000/pulizie -H "X-API-Key: chiave-argento-52de"
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.

Prima di togliere la riga:

{"impresa":"Pulizie Lucente","turni":{"M12":"notte","M14":"mattina","M16":"notte"}}  → 200
{"impresa":"Nettezza Rapida","turni":{"M12":"notte","M14":"mattina","M16":"notte"}}  → 200
{"impresa":"Argento Servizi","turni":{"M12":"notte","M14":"mattina","M16":"notte"}}  → 200

Dopo:

{"impresa":"Pulizie Lucente","turni":{"M12":"notte","M14":"mattina","M16":"notte"}}  → 200
{"detail":"Chiave sbagliata"}  → 401
{"impresa":"Argento Servizi","turni":{"M12":"notte","M14":"mattina","M16":"notte"}}  → 200

Ogni chiave apre come la sua impresa (il return dice chi è). Dopo, la chiave persa non apre più, e le altre due non si sono accorte di niente.

In italiano.

  1. Il controllore legge l'header e, se manca, 401.
  2. Cerca la chiave nel dizionario, con get: l'impresa, oppure None.
  3. Se è None, la chiave non è di nessuno: 401. Altrimenti restituisce l'impresa, e la rotta sa chi chiama.

Passo per passo.

RichiestaCHIAVI.get(chiave)Risposta
chiave-lucente-3f9a"Pulizie Lucente"200, impresa è "Pulizie Lucente"
chiave-rapida-b71c (prima)"Nettezza Rapida"200
chiave-rapida-b71c (dopo)None401 Chiave sbagliata
chiave-argento-52de"Argento Servizi"200

Cosa portiamo a casa. Una chiave per programma: chi perde la sua, la si toglie, e gli altri continuano. Con una chiave sola per tutti, avresti dovuto cambiarla e riscriverla in tre programmi. Col get invece delle quadre, una chiave che non c'è dà un 401 e non un errore del server.