401 Unauthorized: co oznacza i jak naprawić

Co oznacza 401 Unauthorized

RFC 9110 definiuje 401 jako żądanie wymagające uwierzytelnienia, albo dlatego że żadnego nie dostarczono, albo dlatego że to, co dostarczono, nie przeszło. Odpowiedź 401 musi zawierać nagłówek WWW-Authenticate nazywający schemat, którego oczekuje serwer, taki jak Basic, Bearer albo Digest. Ten nagłówek to wskazówka, którą większość osób pomija: mówi dokładnie, jakiego rodzaju poświadczenia chce serwer, co zwykle jest szybsze niż zgadywanie.

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

Jak pojawia się błąd

W przeglądarce 401 chronione HTTP Basic authentication wywołuje natywne okno logowania z nazwą użytkownika i hasłem, nie stronę wyrenderowaną przez witrynę. 401 z API JSON, w przeciwieństwie do tego, zwykle pokazuje się tylko w zakładce sieciowej albo w komunikacie błędu zbudowanym przez aplikację, bo nie ma domyślnego interfejsu przeglądarki dla awarii tokenu Bearer. Z linii poleceń poświadczenie i nagłówek są widoczne w jednym żądaniu:

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"

Logi serwera i aplikacji zwykle też zapisują powód, na przykład "token expired," "signature invalid," albo "no Authorization header," co zawęża przyczynę szybciej niż sam ogólny kod statusu.

Co powoduje 401 Unauthorized

Mniej więcej w kolejności, jak często dana przyczyna się potwierdza:

• W ogóle nie wysłano poświadczeń. Wylogowana sesja, brakujący klucz API albo klient, który nigdy nie dołączył nagłówka Authorization.
• Wygasły token. Ciasteczka sesji, tokeny dostępu OAuth i JWT-y wszystkie mają czas życia, a klient używający nieaktualnego dostaje 401, mimo że działało kilka minut wcześniej.
• Rozjazd zegarów między klientem a serwerem. Roszczenia exp i nbf JWT są oceniane względem zegara serwera. Serwer albo klient z błędnym czasem może odrzucić token, który według własnej matematyki tokenu jest wciąż ważny, albo zaakceptować taki, który już wygasł.
• Zły schemat uwierzytelniania. Wysłanie Authorization: Basic ... do endpointu oczekującego Bearer, albo odwrotnie, zawodzi mimo że nagłówek jest obecny.
• Klucz API umieszczony w złym miejscu. Niektóre API oczekują klucza w niestandardowym nagłówku takim jak X-API-Key, inne w Authorization, a jeszcze inne jako parametr zapytania. Umieszczenie ważnego klucza w złym miejscu wygląda identycznie jak niewysłanie żadnego klucza.
• Reverse proxy albo gateway usuwający nagłówek Authorization. Niektóre konfiguracje proxy i CDN porzucają nagłówki, których jawnie nie przekazują, i zupełnie ważne poświadczenie nigdy nie dociera do serwera źródłowego.
• Unieważnione poświadczenia. Użytkownik zmienił hasło, admin obrócił klucz API, albo token został wprost unieważniony przy wylogowaniu.

401 kontra 403

Oba są często mylone, bo oba odmawiają żądania, ale specyfikacja rysuje wyraźną linię. 401 oznacza, że serwer chce, żebyś się uwierzytelnił, i ważne poświadczenie mogłoby zmienić wynik; musi nieść WWW-Authenticate. 403 oznacza, że serwer dokładnie zrozumiał, kim jesteś, i mimo to odmawia, z powodu, którego uwierzytelnienie nie naprawi, na przykład ograniczenia roli albo planu. Jeśli ponowne zalogowanie prawdopodobnie by pomogło, powinno to być 401. Jeśli użytkownik jest już zalogowany i po prostu nie ma pozwolenia, powinno to być 403, choć w praktyce sporo API luźno używa 401 dla obu przypadków.

Jak rozpoznać, kto zawinił

Jeśli to Ty wywołujesz API, odtwórz żądanie ze świeżym poświadczeniem z czystego środowiska; jeśli nowo wydany token się powiedzie, stary po prostu wygasł albo został unieważniony. Jeśli zupełnie nowy token też zawodzi, sprawdź schemat i nazwę nagłówka względem dokumentacji API, zanim założysz, że serwer jest zepsuty. Jeśli prowadzisz usługę, a użytkownicy zgłaszają 401, których nie potrafisz odtworzyć własnym kontem, najszybszym sposobem rozdzielenia "serwer jest w porządku, poszczególne tokeny są nieaktualne" od "samo uwierzytelnianie jest zepsute dla wszystkich" jest uruchomienie kontroli HTTP ze znanym dobrym poświadczeniem z kilku lokalizacji naraz i porównanie wyników.

Jak naprawić 401 Unauthorized

Jeśli jesteś odwiedzającym

1. Zaloguj się ponownie. Większość 401 z aplikacji webowej to po prostu wygasła sesja, a zalogowanie ją odświeża.
2. Sprawdź zegar systemowy na swoim urządzeniu, jeśli to samo logowanie ciągle zawodzi natychmiast po uwierzytelnieniu. Zegar odstający o kilka minut może unieważnić tokeny czasowe na niektórych klientach.
3. Wygeneruj ponownie klucz API albo token w ustawieniach konta, jeśli podejrzewasz, że został obrócony albo unieważniony, zamiast zakładać błąd w swoim kodzie integracji.
4. Potwierdź, że nagłówek Authorization faktycznie jest wysyłany, za pomocą zakładki sieciowej przeglądarki albo zwykłego wywołania curl, bo niektóre biblioteki klienta HTTP po cichu usuwają niestandardowe nagłówki przy przekierowaniu.

Jeśli prowadzisz witrynę

1. Przeczytaj nagłówek WWW-Authenticate i własne logi pod kątem konkretnego powodu odrzucenia, zanim cokolwiek zmienisz; "expired," "invalid signature" i "missing header" każde wskazuje na inną naprawę.
2. Sprawdź synchronizację zegarów na serwerach wystawiających i walidujących tokeny. Dryf NTP po którejkolwiek stronie to klasyczna, sporadyczna przyczyna odrzuceń JWT, które poza tym wyglądają losowo.
3. Zweryfikuj, że proxy albo load balancer przekazuje nagłówek Authorization. Reguła dodana z niepowiązanego powodu może po cichu usuwać go dla każdego żądania za tym skokiem.
4. Udokumentuj wyraźnie oczekiwany schemat i nazwę nagłówka w dokumentacji API i zwracaj konkretny error_description w nagłówku WWW-Authenticate, żeby integratorzy nie musieli zgadywać.
5. Rozróżnij 401 od 403 we własnych odpowiedziach tam, gdzie ma to znaczenie dla wywołujących, żeby kod klienta mógł odróżnić "odśwież swój token" od "nigdy nie będzie Ci wolno tego zrobić".

Jak zapobiec cichej awarii 401

401 spowodowane wygasłym certyfikatem podpisującym, zegarem, który zdryfował z synchronizacji, albo zmianą proxy, która zaczęła usuwać nagłówek Authorization, nie będzie wyglądać jak awaria. Usługa odpowiada natychmiast i poprawnie według własnych zasad, więc może siedzieć zepsuta dla każdego wywołującego, dopóki ktoś tego nie zauważy. Kontrola HTTP z asercją na oczekiwanym kodzie statusu, uruchamiana z żywym poświadczeniem wobec uwierzytelnionego endpointu, wyłapuje to w chwili, gdy zaczyna się dziać. Dla API konkretnie, połączenie tego z monitorowaniem API, które sprawdza treść odpowiedzi, a nie tylko kody statusu, wyłapuje też token, który się uwierzytelnia, ale zwraca wadliwe dane.

Powiązane błędy

Zobacz 403 Forbidden dla żądań, które serwer zrozumiał i odrzucił niezależnie od poświadczeń, przegląd 4xx dla szerszej rodziny błędów klienta oraz pozostałe poradniki z tej partii: 405 Method Not Allowed, 422 Unprocessable Content.

Najczęściej zadawane pytania

Dlaczego dostaję 401 zaraz po udanym zalogowaniu?

Zwykle rozjazd zegarów między Twoim urządzeniem a serwerem, albo klient, który zbuforował stary, teraz nieważny token, zamiast użyć świeżo wydanego. Potwierdź, że czas systemowy jest poprawny i że faktycznie wysyłany jest nowy token.

Czy 401 oznacza, że moje konto zostało zhakowane?

Nie samo w sobie. Niemal zawsze oznacza wygasłą sesję, unieważniony klucz albo nagłówek wysłany niepoprawnie. Traktuj to jako obawę bezpieczeństwa tylko wtedy, gdy nie spodziewałeś się, że poświadczenie przestanie działać, i nie potrafisz wyjaśnić dlaczego.

Jaka jest różnica między 401 a awarią uwierzytelnienia na warstwie TLS?

Awaria certyfikatu klienta TLS uniemożliwia nawiązanie połączenia w ogóle, więc żaden kod statusu HTTP nigdy nie zostaje zwrócony. 401 oznacza, że połączenie się udało, a serwer otrzymał pełne żądanie HTTP, a potem odrzucił je na poziomie aplikacji za brak ważnych poświadczeń.

Czy formularz logowania sam powinien kiedykolwiek zwracać 401?

Nie. Endpoint logowania oceniający nazwę użytkownika i hasło nie uwierzytelnia istniejącego żądania; złe hasło jest tam zwyczajowo 400 albo 200 z ładunkiem błędu, skoro cały cel endpointu to przyjęcie nieuwierzytelnionych prób i ich osądzenie.

Czy ważny klucz API wciąż może wyprodukować 401?

Tak, jeśli jest wysłany w złym nagłówku albo złym schemacie, jeśli został obrócony po tym, jak Twoja integracja zbuforowała stary, albo jeśli żądanie dotarło do serwera przez proxy, które usunęło nagłówek przed przekazaniem dalej.