Le API HTTP autenticano i chiamanti con una credenziale nell'header Authorization — una API key o un bearer token (Authorization: Bearer <token>). Gli schemi più robusti firmano ogni richiesta con HMAC su una canonical request così che le credenziali non siano mai riproducibili, usano OAuth 2.0 client-credentials per token machine-to-machine e aggiungono mutual TLS dove serve un'identità a livello di transport.
Bearer token e API key
L'autenticazione più semplice è una credenziale bearer: il client presenta un token segreto nell'header Authorization e il server lo valida. RFC 9110 definisce l'header Authorization e il suo prefisso di schema, e OAuth 2.0 definisce lo schema Bearer — Authorization: Bearer <token> — la cui proprietà distintiva è che il semplice possesso concede l'accesso, quindi il token deve viaggiare solo su TLS e non comparire mai in un URL, in un log o in un messaggio di errore. Una API key è la stessa idea con un segreto a vita più lunga, spesso senza scadenza. Poiché una credenziale bearer è riproducibile se catturata, è la base e non il tetto: è facile da integrare e perfettamente adeguata su TLS per la maggior parte del traffico, ma le operazioni ad alto valore spesso vi sovrappongono la firma delle richieste.
POST /v1/messages HTTP/1.1
Host: api.example
Authorization: Bearer eyJhbGciOi... # secret; TLS only, never logged
Content-Type: application/jsonFirma HMAC delle richieste
La firma delle richieste alza l'asticella: invece di inviare il segreto, il client lo usa per calcolare un HMAC su una rappresentazione canonica della richiesta e invia solo la firma. Il server, che detiene lo stesso segreto, ricalcola la firma e confronta. Poiché la firma copre il metodo, il path, gli header chiave e un hash del body, una firma catturata non può essere riprodotta contro una richiesta diversa, e poiché il segreto stesso non lascia mai il client, catturare una richiesta non rivela la credenziale. La costruzione rispecchia la firma dei webhook nell'altra direzione ed è la stessa primitiva HMAC-SHA256 (RFC 2104 / RFC 6234). La parte delicata è la canonical request: entrambe le parti devono concordare byte per byte su come serializzarla, altrimenti ogni firma non corrisponde.
canonical =
HTTP-METHOD + '\n' +
URI-PATH + '\n' +
SORTED-QUERY + '\n' +
SIGNED-HEADERS (name:value, sorted, '\n'-joined) + '\n' +
HEX(SHA256(raw_body))
signature = HMAC_SHA256(secret, canonical)
Authorization: SIGV1 Credential=<key-id>,
SignedHeaders=host;x-date;content-type, Signature=<hex>Header firmati e data della richiesta
Due dettagli rendono solida la firma delle richieste. Primo, una lista SignedHeaders esplicita nomina esattamente quali header sono coperti, così che un intermediario che aggiunge o riordina header non correlati non invalidi la firma, mentre qualsiasi header che il client ha scelto di firmare è a prova di manomissione. Secondo, una data della richiesta (un X-Date firmato o l'header standard Date) fa parte della canonical request e viene confrontata con l'orologio del server entro una tolleranza — la stessa difesa dal replay dei webhook, applicata alle chiamate API in ingresso. Insieme fanno sì che una richiesta firmata sia legata al suo contenuto esatto, ai suoi header dichiarati e a una finestra temporale stretta; una richiesta catturata è inutile pochi minuti dopo.
Scoping e rotazione delle chiavi
Le credenziali dovrebbero portare il privilegio minimo che funziona ed essere ruotabili senza downtime. Lo scoping associa permessi a una chiave — quali operazioni può chiamare, da quale sorgente, a quale rate — così che una chiave che può solo inviare messaggi non possa leggere le impostazioni dell'account, e il raggio d'azione di una chiave trapelata sia delimitato. La rotazione segue il pattern delle chiavi sovrapposte: emetti una nuova credenziale, esegui entrambe in parallelo mentre i client migrano, poi revoca quella vecchia, così nulla si rompe a metà volo. Le chiavi dovrebbero essere identificabili (un key id non segreto viaggia nella richiesta così che il server sappia contro quale segreto verificare e quale scope applicare) e revocabili individualmente, così che un'integrazione compromessa venga esclusa senza disturbare le altre.
| Schema | Cosa viene trasmesso | Forza / utilizzo |
|---|---|---|
| Chiave API | Segreto di lunga durata nell'header Authorization | Base semplice; solo TLS; facile da esporre nei log |
| Bearer token (OAuth 2.0) | Token di accesso di breve durata | In scadenza, con scope; rinnovato tramite l'endpoint del token |
| Firma HMAC delle richieste | Firma (il segreto resta locale) | Resistente al replay e con evidenza di manomissione per ogni richiesta |
| mTLS | Certificato client X.509 | Identità a livello di trasporto; forte ma con gestione più onerosa |
Mutual TLS
Il mutual TLS autentica il client a livello di transport: oltre a presentare il server un certificato, il client presenta il proprio certificato X.509 durante l'handshake, e il server ammette solo le connessioni il cui certificato si incatena a una CA fidata e corrisponde a un'identità registrata. Questo lega l'identità API a una chiave crittografica gestita a livello di connessione anziché a un segreto bearer in un header, il che è interessante per i collegamenti machine-to-machine ad alta garanzia e per vincolare un partner a certificati specifici. Il costo è operativo — emissione, distribuzione, rotazione e revoca dei certificati — quindi il mTLS è tipicamente riservato alle integrazioni più sensibili, spesso combinato con un bearer token o una firma per l'autorizzazione a grana fine sopra l'identità grossolana di transport.
OAuth 2.0 client-credentials per il M2M
Per le integrazioni server-to-server senza alcun utente finale presente, OAuth 2.0 (RFC 6749) definisce il grant client-credentials. Il client si autentica presso un token endpoint con il suo client_id e client_secret (o un certificato client) e riceve un access token a vita breve, che poi presenta come bearer token sulle chiamate API finché non scade e viene rinnovato. Il vantaggio rispetto a una API key statica è la vita e lo scope: i token sono a vita breve, così un token catturato scade rapidamente, e portano scope espliciti, così un token generato per l'invio non può essere usato per amministrare l'account. Questo è il pattern standard per l'accesso API machine-to-machine e il meccanismo che la guida all'autenticazione di BroadNet documenta concretamente per i suoi endpoint.
POST /oauth/token HTTP/1.1
Host: auth.example
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
&client_id=<id>
&client_secret=<secret>
&scope=messages:send
-> { "access_token": "...", "token_type": "Bearer",
"expires_in": 3600, "scope": "messages:send" }Domande frequenti
Qual è la differenza tra un bearer token e la firma HMAC?
Un bearer token è inviato a ogni richiesta e concede l'accesso per possesso, quindi un token catturato è riproducibile finché non scade. La firma HMAC non invia mai il segreto — il client firma una canonical request e invia solo la firma, così una richiesta catturata non può essere riprodotta contro una chiamata diversa e la credenziale stessa non è mai esposta.
Perché la firma HMAC ha bisogno di una canonical request?
Perché entrambe le parti devono calcolare la stessa identica stringa per ottenere firme corrispondenti. La canonical request fissa esattamente come metodo, path, query ordinata, header firmati e hash del body vengono serializzati. Qualsiasi disaccordo — ordine degli header, spazi, un body ricodificato — produce una firma diversa e la richiesta viene rifiutata anche se nulla è stato manomesso.
Cosa mi dà OAuth 2.0 client-credentials rispetto a una API key?
Vita breve e scope esplicito. Il client scambia le sue credenziali presso un token endpoint con un access token a vita breve e con scope (RFC 6749). Un token catturato scade rapidamente, e un token generato per l'invio non può amministrare l'account. Una API key statica, al contrario, è a vita lunga e tipicamente ampia.
Come dovrebbero essere ambito e ruotate le API key?
Concedi il privilegio minimo — limita ogni chiave alle operazioni, alle sorgenti e al rate di cui ha bisogno — così che una fuga sia contenuta. Ruota con chiavi sovrapposte: emetti una nuova credenziale, esegui entrambe in parallelo mentre i client migrano, poi revoca quella vecchia. Le chiavi dovrebbero portare un key id non segreto ed essere revocabili individualmente così che un'integrazione compromessa venga esclusa da sola.
Quando vale il mutual TLS il costo operativo?
Quando ti serve un'identità crittografica a livello di transport per un collegamento machine-to-machine ad alta garanzia, o per vincolare un partner a certificati specifici. Il mTLS ammette solo i client il cui certificato X.509 si incatena a una CA fidata. È più oneroso da gestire — emissione, rotazione, revoca — quindi è di solito riservato alle integrazioni più sensibili, spesso sovrapposto a un token o a una firma per l'autorizzazione.
Perché le credenziali bearer non devono mai comparire in un URL o in un log?
Perché una credenziale bearer concede l'accesso per solo possesso. Gli URL vengono registrati dai proxy, memorizzati nella cronologia del browser e diffusi via header Referer, e i log applicativi sono ampiamente leggibili, quindi un token in uno qualsiasi di essi è di fatto divulgato. Le credenziali bearer devono viaggiare solo nell'header Authorization su TLS ed essere ripulite dai log.
Specifiche della fonte
Gli standard pubblicati su cui si basa questa pagina. Si apre in una nuova scheda.