Vai al contenuto
code-to-code

Apro l'indice…

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

Login e sicurezza2. La chiave: API Keyp. 24

La chiave: API Key

Chi bussa alla porta? La risposta più semplice è una chiave

  • 15 minuti di lettura

Nel capitolo 1 hai visto le due domande: chi sei? e cosa puoi fare?. Qui ti serve la prima, nella forma più semplice che esista.

Il magazzino ricambi del deposito ha un'API. Ogni notte il programma di un fornitore, Valdora Ricambi, la interroga per leggere le scorte di guarnizioni, fusibili e fari. Nessuna persona è davanti a uno schermo: parla un programma con un altro programma. Come fa il magazzino a sapere che a bussare è proprio Valdora, e non un curioso qualunque?

Gli dà una chiave. Chi la porta, entra.

Il server non ricorda

Un controllore a un tornello di Porta Codice non ha memoria. Ti guarda, ti lascia passare, e un secondo dopo non sa più chi sei. Se torni indietro, sei di nuovo uno sconosciuto.

Un server fa lo stesso. Ogni richiesta arriva come se fosse la prima: il server non si ricorda di quella di un secondo fa. Si dice che HTTP è senza stato.

  GET /magazzino   ───────────▶   Server:  «E tu chi sei?»
  GET /magazzino   ───────────▶   Server:  «E tu chi sei?»
  GET /magazzino   ───────────▶   Server:  «E tu chi sei?»

Le tre richieste vengono dallo stesso programma, a un secondo di distanza, ma per il server sono tre sconosciuti. Ne segue una regola semplice: la prova di chi sei deve viaggiare dentro ogni richiesta, ogni volta, da capo.

Dove? Per capirlo, apri una richiesta.

La richiesta, a pezzi

Una richiesta ha tre parti, come una busta con una lettera:

POST /consegne HTTP/1.1                          <- 1. la riga: il verbo e dove va
Host: 127.0.0.1:8000                             <- 2. gli header: le scritte sulla busta,
Content-Type: application/json                      «nome: valore», uno per riga
X-API-Key: 9f2c4e7a1b6d0e83c5a2f4b7d9e1c3a5

{"ricambio": "guarnizione-P12", "pezzi": 50}     <- 3. il corpo: la lettera dentro
  1. La riga: il verbo (GET, POST…) e il percorso. Anche la query (?ordine=nome) sta qui.
  2. Gli header: informazioni sulla richiesta, una per riga, nella forma nome: valore. Sono come le scritte sulla busta: il mittente, il tipo di lettera.
  3. Il corpo: la lettera. Ce l'hanno solo POST e PUT: una GET ha riga e header, e basta.

Gli header li hai già usati senza saperlo:

HeaderValoreChi lo metteQuando
Content-Typeapplication/jsonPostman, o la libreria che usiOgni POST e PUT con un corpo JSON
AuthorizationBearer eyJhbGciOi…il client, con il bigliettoDal capitolo 5
X-API-Key9f2c4e7a1b6d…il client, con la chiaveIn questo capitolo

L'header è il posto giusto per la prova di chi sei perché c'è in ogni richiesta, anche in una GET senza corpo. E il server legge gli header prima del corpo: se la chiave non va, il corpo non lo apre nemmeno.

Il 401, in breve

Se la chiave manca o non va, il server risponde 401: non so chi sei. Il nome inganna («Unauthorized» sembra «non autorizzato»), ma vuol dire «non autenticato»: lo spiega il capitolo 1. Il 403 («so chi sei, ma qui no») qui non serve ancora: ne vedi un assaggio negli esercizi, e il capitolo sui permessiin arrivo lo spiega bene.

L'API Key

API Key vuol dire «chiave dell'API». Funziona in tre mosse:

  1. La dà il server, una volta sola, a mano. Si genera, si copia, si consegna a Valdora. Niente login, niente password.
  2. Viaggia in un header. A ogni richiesta, sempre la stessa: X-API-Key: seguito dalla chiave.
  3. Il server confronta. Ha la sua copia, nel file .env. Uguale: entri. Diversa, o assente: 401.

È una chiave per i programmi: si chiama server to server, da programma a programma. Il gestionale di un fornitore, l'app che chiama un servizio meteo. Nessuna persona fa il login. Le persone avranno una password e un biglietto: capitoli 4, 5 e 6.

I due lati della chiave

La chiave ha due lati, e a seconda del giorno li incontri tutti e due.

Sei tu il client. Chiami un'API di qualcun altro, e te la chiede. Ti registri sul sito del servizio, ti danno una chiave, e tu la metti nell'header di ogni richiesta. Il programma di Valdora fa questo:

Python
import os

import httpx
from dotenv import load_dotenv

load_dotenv()
CHIAVE = os.environ["CHIAVE_MAGAZZINO"]  # dal file .env

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

headers= è un dizionario: nome dell'header, valore. La chiave non è scritta nel codice: viene dall'ambiente, di cui parliamo tra poco.

Sei tu il server. La tua API apre solo a un programma. La chiave la generi tu, la dai al programma, e la controlli a ogni richiesta. È il magazzino di oggi, e il resto del capitolo racconta questo lato.

Fare la chiave

Una chiave deve essere lunga e a caso: 1234 si indovina in un attimo. La fa Python, con il modulo secrets, una volta sola, dalla cartella del progetto:

Terminale
python3 -c "import secrets; print('CHIAVE_MAGAZZINO=' + secrets.token_hex(16))" > .env
cat .env
CHIAVE_MAGAZZINO=6085ac6ded1fa2505cd0b84cdfac423a

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 comando, a pezzi:

PezzoCosa fa
python3 -c "…"esegue la riga di Python che c'è tra le virgolette
secrets.token_hex(16)tira fuori 16 byte a caso e li scrive in esadecimale: 32 caratteri, cifre e lettere da a a f
'CHIAVE_MAGAZZINO=' + …ci attacca davanti il nome e l'uguale: NOME=valore
print(…)stampa la riga
> .envinvece di mostrarla, la scrive nel file .env

Perché secrets e non random? random è fatto per i giochi: i suoi numeri sembrano a caso, ma seguono una regola che si può ricostruire. secrets è fatto per quello che deve restare segreto. Per una chiave, una password o un biglietto si usa sempre secrets.

Il file .env

Un file .env è un file di testo con una riga per voce, nella forma NOME=valore. Ci tieni quello che non si scrive nel codice: chiavi, password, indirizzi segreti. Comincia con un punto, quindi ls non lo mostra: con ls -a sì (nel Finder del Mac: Cmd+Shift+.).

La libreria python-dotenv (pip install python-dotenv) lo legge e mette le voci nell'ambiente, cioè in os.environ, un dizionario da cui Python le prende:

Python
import os

from dotenv import load_dotenv

load_dotenv()
print(os.environ.get("CHIAVE_MAGAZZINO"))

load_dotenv() cerca il .env partendo dalla cartella del file e salendo; se una voce c'è già nell'ambiente, non la cambia. Prima di chiamarla, os.environ.get("CHIAVE_MAGAZZINO") dà None; dopo, la chiave. Lo vedi con i tuoi occhi negli esercizi spiegati.

Due compagni del .env:

  • .gitignore: una riga .env dentro dice a Git di non caricarlo mai. Il .env vero non va mai su GitHub.
  • .env.example: il modello, con una chiave finta. Quello sì che si carica: dice a chi scarica il progetto quali voci servono, senza regalargli la tua chiave.

Il controllore, in italiano

Ora il lato server. A ogni richiesta, il magazzino deve decidere. Prima a parole:

inizio arriva una richiesta leggo l'header X-API-Key, il valore finisce in chiave se chiave è None (l'header non c'è) sì: errore 401 Manca la chiave se chiave è diversa da quella nel .env sì: errore 401 Chiave sbagliata restituisci il fornitorearriva una richiestaleggo l'header X-API-Key, ilvalore finisce in chiavechiave è None(l'header non c'è)401 Manca la chiavechiave è diversa daquella nel .env401 Chiave sbagliatarestituisci il fornitorenosìnosì
Il controllore delle chiavi

Due 401 con due messaggi diversi: chi configura il programma capisce subito se la chiave non è arrivata o se è quella sbagliata. (Al login con la password sarà il contrario: lì un solo messaggio, per un buon motivo, che vedi nel capitolo 4.)

Il controllore, in Python

Python
import os

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

load_dotenv()
CHIAVE_MAGAZZINO = os.environ.get("CHIAVE_MAGAZZINO")
if not CHIAVE_MAGAZZINO:
    raise RuntimeError("Manca CHIAVE_MAGAZZINO: crea il file .env")

FORNITORE = "Valdora Ricambi"
SCORTE = {"guarnizione-P12": 140, "fusibile-F5": 62, "faro-led-M": 9}

app = FastAPI(title="Il magazzino ricambi")


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_MAGAZZINO:
        raise HTTPException(status_code=401, detail="Chiave sbagliata")
    return FORNITORE

In cima, la chiave viene dall'ambiente, e se non c'è il programma si ferma subito con un messaggio chiaro: meglio che partire senza chiave e rompersi alla prima richiesta.

La riga nuova è quella del parametro. Leggila a pezzi:

Python
chiave: str | None = Header(default=None, alias="X-API-Key")
PezzoCosa vuol dire
chiaveil nome in Python: lo scegli tu, è la variabile che userai nella funzione
str | Noneil tipo: una stringa, oppure None se l'header non c'è
Header(…)da dove: dagli header della richiesta, non dal percorso e non dal corpo
default=Nonecosa vale se l'header manca: None, e la funzione decide. Senza default=None, FastAPI risponde da solo 422 e il tuo messaggio non esce mai
alias="X-API-Key"il nome nella richiesta, trattino compreso. In Python un nome non può avere il trattino: l'alias fa da ponte

Due cose da notare. La prima: controlla_chiave è una funzione senza @app. Non è una rotta: nessuno la chiama con un indirizzo. La chiama FastAPI, prima della rotta. La seconda: restituisce il nome del fornitore. Quel valore finirà alla rotta.

La rotta protetta

Python
@app.get("/magazzino")
def leggi_magazzino(fornitore: str = Depends(controlla_chiave)) -> dict:
    return {"fornitore": fornitore, "scorte": SCORTE}

Il parametro fornitore: str = Depends(controlla_chiave) è l'unica riga che protegge la rotta. Il senso, quanto basta per ora: prima parte controlla_chiave. Se fa un raise, la risposta è quella (il 401) e la rotta non parte nemmeno. Se fa un return, il valore finisce nel parametro fornitore, e solo allora parte la rotta.

Lo conosci già da Depends(get_db) nel libro sul database. Come lavora davvero FastAPI, passo per passo, lo spiega da zero il prossimo capitolo.

Da dove arriva ogni dato

Il nome di un parametro lo scegli tu. Da dove arriva lo dice il tipo, oppure Header(…) e Depends(…). È la tabella del libro sul database, con una riga in più:

Da doveNella richiestaNel defCome lo riconosce FastAPI
PercorsoGET /treni/M12codice: strc'è {codice} nel decoratore
QueryGET /treni?ordine=kmordine: str = "id"un tipo semplice, non nel percorso
Corpo{"ricambio": "fusibile-F5", …}dati: Consegnail tipo è uno stampo (BaseModel)
HeaderX-API-Key: 9f2c…chiave: str | None = Header(…)c'è Header(…)
Dipendenzaniente: la prepara FastAPIfornitore: str = Depends(controlla_chiave)c'è Depends(…)

Provarla

Accendi il programma (con il .env nella stessa cartella): fastapi dev magazzino.py. Poi tre modi, tutti con le stesse tre richieste: senza chiave, con una chiave a caso, con la chiave giusta.

Con curl. L'opzione -H aggiunge un header:

Terminale
curl -s -w "  → %{http_code}\n" http://127.0.0.1:8000/magazzino
curl -s -w "  → %{http_code}\n" http://127.0.0.1:8000/magazzino -H "X-API-Key: abc123"
curl -s -w "  → %{http_code}\n" http://127.0.0.1:8000/magazzino -H "X-API-Key: 6085ac6ded1fa2505cd0b84cdfac423a"
{"detail":"Manca la chiave"}  → 401
{"detail":"Chiave sbagliata"}  → 401
{"fornitore":"Valdora Ricambi","scorte":{"guarnizione-P12":140,"fusibile-F5":62,"faro-led-M":9}}  → 200

(-s toglie il resto del rumore, e -w aggiunge in fondo il codice della risposta.) Tre richieste, tre risposte, e il server non ricorda niente: confronta, ogni volta, da capo.

La richiestaIl controlloreLa risposta
GET /magazzino, nessun headerchiave è None401 Manca la chiave
GET /magazzino, X-API-Key: abc123chiave != CHIAVE_MAGAZZINO401 Chiave sbagliata
GET /magazzino, X-API-Key: 6085…uguale: passa200, e fornitore vale "Valdora Ricambi"

Da /docs. Apri http://127.0.0.1:8000/docs. Tra i parametri di GET /magazzino compare un campo X-API-Key, come se fosse un parametro della rotta: è il parametro del controllore, e FastAPI lo mostra. Try it out, scrivi la chiave nel campo, Execute. Lascialo vuoto e ottieni il primo 401.

Da Postman. Scheda Authorization → Auth Type: API Key. In Key scrivi X-API-Key, in Value la chiave, e in Add to scegli Header. Per non ricopiare la chiave a ogni richiesta, mettila in una variabile della collezione (come baseUrl, nel capitolo su Postman e curl) e scrivi {{chiave}} nel Value. Postman aggiunge da solo l'header X-API-Key: lo trovi, con tutti gli altri, nella scheda Headers.

Più chiavi: una per programma

Una chiave sola per tutti ha un guaio: se la perde un fornitore, la devi cambiare per tutti. Meglio una chiave per programma: un dizionario chiave → chi è.

Python
CHIAVI = {
    "chiave-lucente-3f9a": "Pulizie Lucente",
    "chiave-rapida-b71c": "Nettezza Rapida",
    "chiave-argento-52de": "Argento Servizi",
}


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

Il get lo conosci dai dizionari: None se la chiave non c'è, senza errori. Il return ora dice chi è: ogni rotta sa quale programma sta chiamando. E se uno la perde, togli la sua riga dal dizionario e gli altri continuano a lavorare. (Chiavi scritte nel codice, qui, solo per imparare: sono finte. Quelle vere stanno nel .env o in un database.)

Le trappole

Quando la chiave non basta

La chiave è comoda per un programma, ma ha tre limiti:

  • Non sa quale persona c'è dietro. Dice «è Valdora», non «è Rosa Bellini». Il controllore con più chiavi dice quale programma, non quale persona.
  • Non scade. Una chiave rubata funziona finché qualcuno non se ne accorge.
  • È sempre la stessa. Ogni richiesta porta la stessa prova: chi la intercetta una volta, la ha per sempre.

Per le persone serve il login: la password (capitolo 4), che si dà una volta sola, e il biglietto (capitolo 5), che scade ed è firmato. Il controllore del biglietto (capitolo 6) avrà la stessa forma di questo: cambia solo cosa legge e cosa restituisce.

Ricorda

  • Il server non ricorda: la prova di chi sei viaggia dentro ogni richiesta.
  • Una richiesta ha la riga, gli header (nome: valore) e il corpo (solo POST e PUT). La chiave sta in un header: X-API-Key.
  • L'API Key la dà il server a mano, è sempre la stessa, ed è per i programmi. Il server la confronta con la sua copia nel .env.
  • La chiave si fa con secrets.token_hex(16), mai con random, e si tiene nel .env: mai nel codice, mai su GitHub.
  • Il controllore: manca → 401 «Manca la chiave»; è diversa → 401 «Chiave sbagliata»; è giusta → restituisce chi è. È una funzione senza @app.
  • chiave: str | None = Header(default=None, alias="X-API-Key"): senza default=None, 422.
  • La rotta si protegge con una riga: fornitore: str = Depends(controlla_chiave).
  • Una chiave per programma: un dizionario chiave → chi è. Chi perde la sua, la si toglie.