401 Unauthorized: cosa significa e come risolverlo

Cosa significa 401 Unauthorized

RFC 9110 definisce il 401 come una richiesta che richiede autenticazione, o perché non ne è stata fornita alcuna o perché quella fornita non è passata. Una risposta 401 deve includere un header WWW-Authenticate che nomina lo schema che il server si aspetta, come Basic, Bearer, o Digest. Quell'header è l'indizio che la maggior parte delle persone salta: ti dice esattamente che tipo di credenziale vuole il server, il che di solito è più veloce che indovinare.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api", error="invalid_token"

Come appare l'errore

In un browser, un 401 protetto da autenticazione HTTP Basic innesca il prompt nativo per nome utente e password, non una pagina visualizzata dal sito. Un 401 da un'API JSON, al contrario, di solito compare solo in una scheda di rete o in un avviso toast che l'applicazione ha costruito per esso, dato che non esiste un'interfaccia predefinita del browser per un fallimento di Bearer token. Dalla riga di comando, la credenziale e l'header sono entrambi visibili in una sola richiesta:

curl -i -H "Authorization: Bearer eyJhbGciOi..." https://api.example.com/v1/account
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="token is expired"

I log del server e dell'applicazione di solito registrano anche il motivo, per esempio "token expired," "signature invalid," o "no Authorization header," il che restringe la causa più velocemente del solo codice di stato generico.

Cosa causa un 401 Unauthorized

All'incirca nell'ordine di quanto spesso ciascuna risulta essere la causa:

• Nessuna credenziale inviata affatto. Una sessione disconnessa, una chiave API mancante, o un client che non ha mai allegato l'header Authorization fin dall'inizio.
• Un token scaduto. I cookie di sessione, i token di accesso OAuth, e i JWT portano tutti una durata, e un client che ne usa uno obsoleto riceve 401 anche se funzionava minuti prima.
• Disallineamento dell'orologio tra client e server. Le claim exp e nbf di un JWT vengono valutate contro l'orologio del server. Un server o un client con l'ora sbagliata può rifiutare un token che, secondo la matematica del token stesso, è ancora valido, o accettarne uno già scaduto.
• Lo schema di autenticazione sbagliato. Inviare Authorization: Basic ... a un endpoint che si aspetta Bearer, o il contrario, fallisce anche se un header è presente.
• Una chiave API messa nel posto sbagliato. Alcune API si aspettano la chiave in un header personalizzato come X-API-Key, altre in Authorization, e altre come parametro di query. Mettere una chiave valida nel posto sbagliato appare identico a non inviare alcuna chiave affatto.
• Un reverse proxy o gateway che rimuove l'header Authorization. Alcune configurazioni di proxy e CDN scartano header che non inoltrano esplicitamente, e una credenziale perfettamente valida non raggiunge mai l'origine.
• Credenziali revocate. Un utente ha cambiato la propria password, un amministratore ha ruotato una chiave API, o un token è stato esplicitamente invalidato al logout.

401 contro 403

I due vengono spesso confusi perché entrambi rifiutano la richiesta, ma la specifica traccia una linea chiara. Un 401 significa che il server ha bisogno che tu ti autentichi, e una credenziale valida potrebbe cambiare l'esito; deve portare WWW-Authenticate. Un 403 significa che il server ha capito esattamente chi sei e rifiuta comunque, per un motivo che l'autenticazione non può risolvere, come una restrizione di ruolo o di piano. Se effettuare di nuovo il login aiuterebbe plausibilmente, dovrebbe essere 401. Se l'utente è già connesso e semplicemente non gli è permesso, dovrebbe essere 403, anche se in pratica molte API usano il 401 in modo generico per entrambi i casi.

Come capire di chi è la colpa

Se sei tu a chiamare l'API, riproduci la richiesta con una credenziale fresca da un ambiente pulito; se un token appena emesso riesce, quello vecchio era semplicemente scaduto o era stato revocato. Se anche un token completamente nuovo fallisce, controlla lo schema e il nome dell'header contro la documentazione dell'API prima di assumere che il server sia rotto. Se gestisci il servizio e gli utenti segnalano 401 che non riesci a riprodurre con il tuo stesso account, il modo più veloce per distinguere "il server sta bene, singoli token sono obsoleti" da "l'autenticazione stessa è rotta per tutti" è eseguire un controllo HTTP con una credenziale nota come valida da più postazioni contemporaneamente e confrontare i risultati.

Come correggere un 401 Unauthorized

Se sei un visitatore

1. Effettua di nuovo il login. La maggior parte dei 401 da un'app web sono semplicemente una sessione scaduta, e accedere la rinfresca.
2. Controlla l'orologio di sistema sul tuo dispositivo se lo stesso login continua a fallire immediatamente dopo che ti autentichi. Un orologio fuori sincrono di qualche minuto può invalidare i token basati sul tempo su alcuni client.
3. Rigenera una chiave API o un token dalle impostazioni dell'account se sospetti che sia stata ruotata o revocata, invece di assumere che il tuo codice di integrazione abbia un bug.
4. Conferma che l'header Authorization venga effettivamente inviato, usando la scheda di rete del tuo browser o una semplice chiamata curl, dato che alcune librerie client HTTP scartano silenziosamente gli header personalizzati su un redirect.

Se gestisci il sito

1. Leggi l'header WWW-Authenticate e i tuoi stessi log per il motivo specifico del rifiuto prima di cambiare qualcosa; "expired," "invalid signature," e "missing header" indicano ciascuno una correzione diversa.
2. Controlla la sincronizzazione dell'orologio sui server che emettono e convalidano i token. Il drift NTP su uno dei due lati è una causa classica e intermittente di rifiuti JWT che altrimenti sembrano casuali.
3. Verifica che il proxy o il load balancer inoltri l'header Authorization. Una regola aggiunta per un motivo non correlato può rimuoverlo silenziosamente per ogni richiesta dietro quel salto.
4. Documenta chiaramente lo schema e il nome dell'header attesi nella tua documentazione API, e restituisci un error_description specifico nell'header WWW-Authenticate in modo che chi integra non debba indovinare.
5. Distingui il 401 dal 403 nelle tue stesse risposte dove conta per chi chiama, così il codice client può distinguere "rinnova il tuo token" da "non ti sarà mai permesso di farlo."

Come prevenire un'interruzione silenziosa di 401

Un 401 causato da un certificato di firma scaduto, un orologio andato fuori sincrono, o un cambio del proxy che ha iniziato a scartare l'header Authorization non apparirà come un crash. Il servizio risponde istantaneamente e correttamente secondo le proprie regole, quindi può restare rotto per ogni chiamante finché qualcuno non se ne accorge. Un controllo HTTP con un'asserzione sul codice di stato atteso, eseguito con una credenziale attiva contro un endpoint autenticato, coglie questo nel momento in cui inizia a succedere. Per le API in particolare, abbinare questo al monitoraggio API che controlla i corpi delle risposte oltre ai codici di stato coglie anche un token che si autentica ma restituisce dati malformati.

Errori correlati

Vedi 403 Forbidden per richieste che il server ha capito e rifiutato indipendentemente dalle credenziali, la panoramica 4xx per la famiglia più ampia di errori client, e le altre guide in questo lotto: 405 Method Not Allowed, 422 Unprocessable Content.

Domande frequenti

Perché ricevo 401 subito dopo aver effettuato con successo il login?

Di solito un disallineamento dell'orologio tra il tuo dispositivo e il server, oppure un client che ha messo in cache il vecchio token, ora non valido, invece di usare quello appena emesso. Conferma che l'ora del tuo sistema sia corretta e che il nuovo token venga effettivamente inviato.

Il 401 significa che il mio account è stato violato?

Non da solo. Quasi sempre significa una sessione scaduta, una chiave revocata, o un header inviato in modo scorretto. Trattalo come una preoccupazione di sicurezza solo se non ti aspettavi che la credenziale smettesse di funzionare e non riesci a spiegare perché lo abbia fatto.

Qual è la differenza tra 401 e un fallimento di autenticazione a livello TLS?

Un fallimento del certificato client TLS impedisce del tutto che la connessione venga stabilita, quindi non viene mai restituito alcun codice di stato HTTP. Un 401 significa che la connessione è riuscita e il server ha ricevuto una richiesta HTTP completa, poi l'ha rifiutata a livello applicativo per mancanza di credenziali valide.

Un modulo di login stesso dovrebbe mai restituire 401?

No. Un endpoint di login che valuta un nome utente e una password non sta autenticando una richiesta esistente; una password sbagliata lì è convenzionalmente un 400 o un 200 con un payload di errore, dato che lo scopo intero dell'endpoint è accettare tentativi non autenticati e giudicarli.

Una chiave API valida può comunque produrre 401?

Sì, se viene inviata nell'header sbagliato o nello schema sbagliato, se è stata ruotata dopo che la tua integrazione ha messo in cache quella vecchia, o se la richiesta ha raggiunto il server attraverso un proxy che ha scartato l'header prima di inoltrarla.