401 Unauthorized: co to znamená a jak to opravit

Co znamená 401 Unauthorized

RFC 9110 definuje 401 jako požadavek vyžadující autentizaci, buď proto, že žádná nebyla poskytnutá, nebo proto, že to, co bylo poskytnuto, neprošlo. Odpověď 401 musí obsahovat hlavičku WWW-Authenticate pojmenovávající schéma, které server očekává, jako Basic, Bearer, nebo Digest. Tahle hlavička je vodítko, které většina lidí přeskočí: přesně řekne, jaký druh přihlašovacího údaje server chce, což je obvykle rychlejší než hádání.

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

Jak se chyba projevuje

V prohlížeči 401 chráněná HTTP Basic autentizací spustí nativní výzvu k zadání uživatelského jména a hesla, ne stránku vykreslenou webem. 401 z JSON API se naproti tomu obvykle objeví jen na kartě sítě nebo v chybové bublině, kterou pro ni postavila aplikace, protože pro selhání s Bearer tokenem neexistuje žádné výchozí rozhraní prohlížeče. Z příkazové řádky jsou přihlašovací údaj i hlavička viditelné v jednom požadavku:

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"

Logy serveru a aplikace obvykle taky zaznamenají důvod, například "token expired," "signature invalid," nebo "no Authorization header," což zúží příčinu rychleji než samotný obecný stavový kód.

Co způsobuje 401 Unauthorized

Přibližně v pořadí, jak často se každá z příčin ukáže jako ta pravá:

• Nebyly poslány vůbec žádné přihlašovací údaje. Odhlášená relace, chybějící klíč API, nebo klient, který hlavičku Authorization vůbec nepřipojil.
• Vypršelý token. Cookies relace, přístupové tokeny OAuth i JWT nesou dobu platnosti, a klient používající zastaralý token dostane 401, i když fungoval ještě před pár minutami.
• Vychýlení hodin mezi klientem a serverem. Nároky exp a nbf u JWT se vyhodnocují podle hodin serveru. Server nebo klient se špatným časem může odmítnout token, který je podle vlastní matematiky tokenu pořád platný, nebo naopak přijmout takový, jehož platnost už vypršela.
• Špatné schéma autentizace. Odeslání Authorization: Basic ... na endpoint, který očekává Bearer, nebo naopak, selže, i když je hlavička přítomná.
• Klíč API umístěný na špatném místě. Některá API očekávají klíč ve vlastní hlavičce jako X-API-Key, jiná v Authorization, a další jako parametr dotazu. Vložení platného klíče na špatné místo vypadá úplně stejně jako neposlání žádného klíče.
• Reverzní proxy nebo brána odstraňující hlavičku Authorization. Některé konfigurace proxy a CDN zahazují hlavičky, které výslovně nepředávají, a naprosto platný přihlašovací údaj se k originu nikdy nedostane.
• Odvolané přihlašovací údaje. Uživatel si změnil heslo, administrátor otočil klíč API, nebo byl token při odhlášení výslovně zneplatněn.

401 versus 403

Tyhle dva se často pletou, protože oba požadavek odmítnou, ale specifikace vede jasnou hranici. 401 znamená, že server potřebuje, abyste se ověřili, a platný přihlašovací údaj by mohl výsledek změnit; musí nést WWW-Authenticate. 403 znamená, že server přesně pochopil, kdo jste, a přesto to odmítá, z důvodu, který autentizace nemůže napravit, jako omezení role nebo plánu. Pokud by opětovné přihlášení pravděpodobně pomohlo, měla by to být 401. Pokud je uživatel už přihlášený a prostě to nemá povolené, měla by to být 403, i když v praxi hodně API používá 401 volně pro oba případy.

Jak zjistit, čí je to chyba

Pokud API voláte vy, zopakujte požadavek s čerstvým přihlašovacím údajem z čistého prostředí; pokud nově vydaný token uspěje, starý prostě vypršel nebo byl odvolaný. Pokud selže i úplně nový token, zkontrolujte schéma a název hlavičky proti dokumentaci API, než usoudíte, že je server rozbitý. Pokud službu provozujete a uživatelé hlásí 401, které se vám nedaří reprodukovat s vlastním účtem, nejrychlejší způsob, jak oddělit "server je v pořádku, jednotlivé tokeny jsou zastaralé" od "autentizace samotná je rozbitá pro každého", je spustit HTTP kontrolu se známě funkčním přihlašovacím údajem z několika míst najednou a porovnat výsledky.

Jak opravit 401 Unauthorized

Pokud jste návštěvník

1. Přihlaste se znovu. Většina 401 z webové aplikace je prostě vypršelá relace, a přihlášení ji obnoví.
2. Zkontrolujte systémové hodiny na svém zařízení, pokud stejné přihlášení pořád selhává hned po ověření. Hodiny posunuté o pár minut mohou u některých klientů zneplatnit tokeny založené na čase.
3. Znovu vygenerujte klíč API nebo token v nastavení účtu, pokud máte podezření, že byl otočený nebo odvolaný, místo abyste předpokládali chybu ve vlastním integračním kódu.
4. Potvrďte, že se hlavička Authorization skutečně posílá, pomocí karty sítě prohlížeče nebo obyčejného volání curl, protože některé knihovny HTTP klienta potichu zahodí vlastní hlavičky při přesměrování.

Pokud web provozujete

1. Přečtěte si hlavičku WWW-Authenticate a vlastní logy ohledně konkrétního důvodu odmítnutí, než cokoli změníte; "expired," "invalid signature," a "missing header" každé ukazuje na jinou opravu.
2. Zkontrolujte synchronizaci hodin na serverech vydávajících a ověřujících tokeny. Rozjetí NTP na kterékoli straně je klasická, přerušovaná příčina odmítnutí JWT, která jinak vypadají náhodně.
3. Ověřte, že proxy nebo load balancer předává hlavičku Authorization. Pravidlo přidané z nesouvisejícího důvodu ji může potichu odstranit pro každý požadavek za daným skokem.
4. Jasně zdokumentujte očekávané schéma a název hlavičky ve své dokumentaci API a v hlavičce WWW-Authenticate vracejte konkrétní error_description, aby integrátoři nemuseli hádat.
5. Rozlište 401 od 403 ve vlastních odpovědích tam, kde na tom volajícím záleží, aby klientský kód dokázal rozeznat "obnovte si token" od "tohle nikdy dělat nebudete moct".

Jak předejít tichému výpadku 401

401 způsobená vypršelým podepisovacím certifikátem, hodinami, které se rozjely mimo synchronizaci, nebo změnou proxy, která začala zahazovat hlavičku Authorization, nebude vypadat jako pád. Služba odpovídá okamžitě a podle vlastních pravidel správně, takže může zůstat rozbitá pro každého volajícího, dokud si toho někdo nevšimne. HTTP kontrola s ověřením očekávaného stavového kódu, spuštěná se živým přihlašovacím údajem proti autentizovanému endpointu, tohle zachytí ve chvíli, kdy to začne. Konkrétně u API pomůže spárovat to s monitoringem API, který kontroluje i těla odpovědí, ne jen stavové kódy, což zachytí i token, který se ověří, ale vrátí poškozená data.

Související chyby

Viz 403 Forbidden pro požadavky, kterým server porozuměl a odmítl je bez ohledu na přihlašovací údaje, přehled 4xx pro širší rodinu chyb klienta, a další návody v této dávce: 405 Method Not Allowed, 422 Unprocessable Content.

Často kladené otázky

Proč dostanu 401 hned po úspěšném přihlášení?

Obvykle nesoulad hodin mezi vaším zařízením a serverem, nebo klient, který cachoval starý, už neplatný token, místo aby použil nově vydaný. Potvrďte, že máte správný systémový čas a že se skutečně posílá nový token.

Znamená 401, že byl můj účet napadený?

Samo o sobě ne. Skoro vždy znamená vypršelou relaci, odvolaný klíč, nebo špatně poslanou hlavičku. Berte to jako bezpečnostní obavu jen tehdy, když jste nečekali, že přihlašovací údaj přestane fungovat, a nedokážete vysvětlit proč.

Jaký je rozdíl mezi 401 a selháním autentizace na úrovni TLS?

Selhání klientského certifikátu TLS zabrání tomu, aby se spojení vůbec navázalo, takže se nikdy nevrátí žádný stavový kód HTTP. 401 znamená, že se spojení povedlo a server přijal kompletní HTTP požadavek, a pak ho na aplikační úrovni odmítl kvůli chybějícím platným přihlašovacím údajům.

Měl by samotný přihlašovací formulář někdy vracet 401?

Ne. Endpoint přihlášení vyhodnocující uživatelské jméno a heslo neautentizuje existující požadavek; špatné heslo tam je konvenčně 400 nebo 200 s chybovým obsahem, protože celým smyslem endpointu je přijímat neautentizované pokusy a posuzovat je.

Může platný klíč API pořád vyprodukovat 401?

Ano, pokud je poslaný ve špatné hlavičce nebo špatném schématu, pokud byl otočený poté, co si ho vaše integrace cachovala starý, nebo pokud se požadavek dostal k serveru přes proxy, která hlavičku odstranila ještě před předáním.