401 Unauthorized: wat het betekent en hoe u het oplost

Wat 401 Unauthorized betekent

RFC 9110 definieert 401 als een verzoek dat authenticatie vereist, ofwel omdat er geen werd meegeleverd ofwel omdat wat werd meegeleverd niet slaagde. Een 401-antwoord moet een WWW-Authenticate-header bevatten die het schema noemt dat de server verwacht, zoals Basic, Bearer, of Digest. Die header is de aanwijzing die de meeste mensen over het hoofd zien: hij vertelt precies welk soort inloggegeven de server wil, wat meestal sneller is dan gokken.

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

Hoe de fout verschijnt

In een browser triggert een 401 die beveiligd is met HTTP Basic-authenticatie de ingebouwde prompt voor gebruikersnaam en wachtwoord, geen door de site weergegeven pagina. Een 401 van een JSON-API daarentegen verschijnt meestal alleen in een netwerktabblad of een foutmelding die de applicatie er zelf voor heeft gebouwd, aangezien er geen standaard browserinterface bestaat voor een mislukt Bearer-token. Vanaf de commandoregel zijn zowel het inloggegeven als de header in één verzoek zichtbaar:

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"

Server- en applicatielogs registreren meestal ook de reden, bijvoorbeeld "token expired," "signature invalid," of "no Authorization header," wat de oorzaak sneller inperkt dan de generieke statuscode alleen.

Wat een 401 Unauthorized veroorzaakt

Ruwweg in de volgorde van hoe vaak elk ervan de oorzaak blijkt te zijn:

• Er werden helemaal geen inloggegevens meegestuurd. Een uitgelogde sessie, een ontbrekende API-sleutel, of een client die de header Authorization nooit toevoegde.
• Een verlopen token. Sessiecookies, OAuth-toegangstokens, en JWT's dragen allemaal een levensduur, en een client die een verouderd token gebruikt krijgt 401 ook al werkte het minuten eerder nog.
• Klokafwijking tussen client en server. De claims exp en nbf van een JWT worden geëvalueerd tegen de klok van de server. Een server of client met de verkeerde tijd kan een token weigeren dat, volgens de eigen rekensom van het token, nog geldig is, of er een accepteren dat al verlopen is.
• Het verkeerde authenticatieschema. Het versturen van Authorization: Basic ... naar een endpoint dat Bearer verwacht, of andersom, faalt ook al is er een header aanwezig.
• Een API-sleutel op de verkeerde plek. Sommige API's verwachten de sleutel in een aangepaste header zoals X-API-Key, andere in Authorization, en weer andere als queryparameter. Een geldige sleutel op de verkeerde plek zetten ziet er identiek uit aan helemaal geen sleutel versturen.
• Een reverse proxy of gateway die de Authorization-header verwijdert. Sommige proxy- en CDN-configuraties laten headers vallen die ze niet expliciet doorsturen, en een volledig geldig inloggegeven bereikt de origin nooit.
• Ingetrokken inloggegevens. Een gebruiker wijzigde zijn wachtwoord, een beheerder roteerde een API-sleutel, of een token werd expliciet ongeldig gemaakt bij het uitloggen.

401 versus 403

De twee worden vaak verward omdat ze allebei het verzoek weigeren, maar de spec trekt een duidelijke lijn. Een 401 betekent dat de server wil dat u zich authenticeert, en een geldig inloggegeven zou de uitkomst kunnen veranderen; hij moet WWW-Authenticate meedragen. Een 403 betekent dat de server precies begreep wie u bent en toch weigert, om een reden die authenticatie niet kan oplossen, zoals een rol- of pakketbeperking. Zou opnieuw inloggen aannemelijk helpen, dan hoort het 401 te zijn. Is de gebruiker al ingelogd en simpelweg niet toegestaan, dan hoort het 403 te zijn, al gebruiken in de praktijk veel API's 401 losjes voor beide gevallen.

Hoe u vaststelt wiens fout het is

Roept u zelf de API aan, reproduceer het verzoek dan met een vers inloggegeven vanuit een schone omgeving; slaagt een net uitgegeven token, dan was het oude simpelweg verlopen of ingetrokken. Faalt ook een gloednieuw token, controleer dan het schema en de headernaam tegen de documentatie van de API voordat u aanneemt dat de server kapot is. Beheert u de dienst en melden gebruikers 401's die u niet kunt reproduceren met uw eigen account, dan is de snelste manier om "de server is prima, individuele tokens zijn verouderd" te scheiden van "authenticatie zelf is voor iedereen kapot" een HTTP-controle met een bekend geldig inloggegeven vanaf meerdere locaties tegelijk uit te voeren en de resultaten te vergelijken.

Hoe u een 401 Unauthorized oplost

Bent u de bezoeker

1. Log opnieuw in. De meeste 401's van een webapp zijn simpelweg een verlopen sessie, en inloggen ververst die.
2. Controleer de systeemklok op uw apparaat als dezelfde login meteen na het authenticeren blijft falen. Een klok die enkele minuten afwijkt kan tijdgebonden tokens op sommige clients ongeldig maken.
3. Genereer een API-sleutel of token opnieuw vanuit de accountinstellingen als u vermoedt dat die geroteerd of ingetrokken is, in plaats van aan te nemen dat uw integratiecode een bug bevat.
4. Bevestig dat de Authorization-header daadwerkelijk wordt verstuurd, met het netwerktabblad van uw browser of een gewone curl-aanroep, aangezien sommige HTTP-clientbibliotheken aangepaste headers stilzwijgend laten vallen bij een redirect.

Beheert u de site

1. Lees de WWW-Authenticate-header en uw eigen logs voor de specifieke weigeringsreden voordat u iets wijzigt; "expired," "invalid signature," en "missing header" wijzen elk op een andere oplossing.
2. Controleer de kloksynchronisatie op de servers die tokens uitgeven en valideren. NTP-drift aan een van beide kanten is een klassieke, onregelmatige oorzaak van JWT-weigeringen die anders willekeurig lijken.
3. Verifieer dat de proxy of loadbalancer de Authorization-header doorstuurt. Een regel die om een niet-verwante reden werd toegevoegd kan hem stilzwijgend verwijderen voor elk verzoek achter die sprong.
4. Documenteer het verwachte schema en de headernaam duidelijk in uw API-documentatie, en geef een specifieke error_description terug in de WWW-Authenticate-header zodat integrators niet hoeven te gokken.
5. Onderscheid 401 van 403 in uw eigen antwoorden waar dat voor aanroepers van belang is, zodat clientcode "vernieuw uw token" kan onderscheiden van "dit zal u nooit worden toegestaan."

Hoe u een stille 401-storing voorkomt

Een 401 veroorzaakt door een verlopen ondertekeningscertificaat, een klok die uit sync raakte, of een proxywijziging die de Authorization-header is gaan laten vallen, ziet er niet uit als een crash. De dienst antwoordt direct en correct volgens zijn eigen regels, dus kan hij kapot blijven voor elke aanroeper totdat iemand het opmerkt. Een HTTP-controle met een assertie op de verwachte statuscode, uitgevoerd met een live inloggegeven tegen een geauthenticeerd endpoint, vangt dat op het moment dat het begint te gebeuren. Voor API's specifiek vangt API-monitoring die ook responsbody's controleert naast statuscodes ook een token op dat wel authenticeert maar misvormde data teruggeeft.

Gerelateerde fouten

Zie 403 Forbidden voor verzoeken die de server begreep en weigerde ongeacht inloggegevens, het 4xx-overzicht voor de bredere familie van clientfouten, en de andere handleidingen in deze reeks: 405 Method Not Allowed, 422 Unprocessable Content.

Veelgestelde vragen

Waarom krijg ik 401 vlak na succesvol inloggen?

Meestal een klokverschil tussen uw apparaat en de server, of een client die het oude, nu ongeldige token cachete in plaats van het vers uitgegeven token te gebruiken. Bevestig dat uw systeemtijd correct is en dat het nieuwe token daadwerkelijk wordt verstuurd.

Betekent 401 dat mijn account gehackt is?

Niet op zichzelf. Het betekent vrijwel altijd een verlopen sessie, een ingetrokken sleutel, of een verkeerd verstuurde header. Behandel het alleen als een beveiligingskwestie als u niet verwachtte dat het inloggegeven zou stoppen met werken en niet kunt verklaren waarom dat gebeurde.

Wat is het verschil tussen 401 en een authenticatiestoring op TLS-niveau?

Een storing bij een TLS-clientcertificaat verhindert dat de verbinding ooit tot stand komt, dus wordt er nooit een HTTP-statuscode teruggegeven. Een 401 betekent dat de verbinding lukte en de server een volledig HTTP-verzoek ontving, en het vervolgens op applicatieniveau weigerde wegens ontbrekende geldige inloggegevens.

Zou een loginformulier zelf ooit 401 moeten teruggeven?

Nee. Een login-endpoint dat een gebruikersnaam en wachtwoord evalueert, authenticeert geen bestaand verzoek; een verkeerd wachtwoord daar is conventioneel een 400 of een 200 met een foutpayload, aangezien het hele doel van het endpoint is niet-geauthenticeerde pogingen te accepteren en te beoordelen.

Kan een geldige API-sleutel toch 401 opleveren?

Ja, als hij in de verkeerde header of het verkeerde schema wordt verstuurd, als hij geroteerd werd nadat uw integratie de oude cachete, of als het verzoek de server bereikte via een proxy die de header liet vallen voordat hij doorstuurde.