Wyszukaj, jak JWT pasują do uwierzytelniania za pomocą e-maila i hasła, a znajdziesz w kółko te same pytania: czy bezpiecznie jest umieszczać dane uwierzytelniające w tokenie, czy nadal potrzebuję HTTPS, kto ma to czytać i co się dzieje, gdy token wygaśnie? Odpowiedzi są krótkie, a ich prawidłowe zastosowanie to większość pracy.
Ten poradnik przeprowadza przez pełny cykl życia JSON Web Token w aplikacji z logowaniem przez e-mail i hasło, od pierwszej rejestracji po wylogowanie, z użyciem REST API AuthFlow™. Sam format tokenu jest zdefiniowany w RFC 7519; nie musisz go czytać, aby nadążyć.
Czym jest JWT, a czym nie jest
JWT jest wynikiem uwierzytelnienia, a nie jego zamiennikiem. Użytkownik raz potwierdza, kim jest, za pomocą e-maila i hasła. Serwer zwraca następnie podpisany token, który mówi: „ta osoba już się uwierzytelniła”, a każde kolejne żądanie niesie token zamiast hasła. Dzięki temu JWT są przydatne w systemach bezstanowych i rozproszonych: każda usługa posiadająca właściwy klucz może sprawdzić token bez kolejnego zapytania do bazy danych.
JWT składa się z trzech części: nagłówka (typ tokenu i algorytm podpisu), ładunku (payload) z deklaracjami (claims) dotyczącymi użytkownika oraz podpisu. Podpis dowodzi, że token nie został zmieniony. Niczego nie ukrywa. Ładunek jest jedynie zakodowany w base64, więc każdy, kto zdobędzie token, może go odczytać. Traktuj JWT jako zabezpieczony przed modyfikacją, a nie jako tajny.
Nigdy nie umieszczaj hasła w tokenie
Częste pytanie początkujących brzmi, czy dane uwierzytelniające użytkownika można przechowywać w JWT. Zasadniczo nie powinno to być potrzebne: sam token jest krótkotrwałym poświadczeniem wytworzonym przez logowanie. Jeśli musisz zidentyfikować użytkownika, umieść identyfikator w deklaracji sub, a także rolę lub poziom dostępu, jeśli potrzebuje ich Twój backend. Pomiń hasła, sekrety i wszystko, czego nie chciałbyś widzieć w przeglądarce.
HTTPS to osobna kwestia i należy go używać do wszystkiego. Chroni ruch między klientem a serwerem, natomiast podpis JWT chroni integralność tokenu. Jedno nie zastępuje drugiego.
Krok 1: Trzymaj klucz API na swoim serwerze
Każde wywołanie AuthFlow jest wykonywane w imieniu Twojej organizacji, z użyciem klucza API z panelu właściciela. Klucz ten musi znajdować się w infrastrukturze, którą kontrolujesz, na przykład w zmiennej środowiskowej po stronie serwera, takiej jak AUTHFLOW_API_KEY. Nigdy nie umieszczaj go w kodzie JavaScript działającym w przeglądarce. Najprostszym bezpiecznym rozwiązaniem jest niewielki backend (lub publikowane przez nas proxy ExpressJS), z którym komunikuje się Twój frontend i który w jego imieniu komunikuje się z /auth.
Krok 2: Rejestracja i logowanie
Przed rejestracją lub logowaniem Twój backend żąda od /auth/fooBar krótkotrwałego tokenu zapobiegającego nadużyciom dla adresu e-mail użytkownika. Wygasa on po 45 sekundach, więc pobieraj go bezpośrednio przed kolejnym wywołaniem i nigdy nie używaj ponownie. Następnie wywołaj /auth/signUp z wartością foobar, swoim api_key, polem email, polem password spełniającym regułę złożoności (od 8 do 32 znaków, z wielką i małą literą, cyfrą i znakiem specjalnym), polem fullname oraz disclaimed ustawionym na true. Udana rejestracja od razu zwraca token sesji, a zduplikowany e-mail i rola skutkują odpowiedzią 409.
Logowanie działa tak samo, przez /auth/login. W przypadku powodzenia otrzymujesz token sesji: JWT podpisany algorytmem RS512. RS512 używa pary kluczy, więc tokeny są podpisywane kluczem prywatnym, którego nigdy nie widzisz, i można je weryfikować bez udostępniania jakiegokolwiek sekretu.
Krok 3: Ostrożnie przechowuj token
Gdy Twój backend ma już token, zdecyduj, gdzie będzie przechowywany. Zalecaną opcją są ciasteczka HTTP-only, ponieważ skrypty strony nie mogą ich odczytać, co ogranicza skutki błędu typu cross-site scripting. Cokolwiek wybierzesz, przechowuj token sesji, a nie tymczasowy, i dopilnuj, aby nigdy nie był zapisywany w logach.
Krok 4: Weryfikuj przy każdej chronionej trasie
Zanim Twój backend obsłuży chronione żądanie, sprawdź token. Wywołaj /auth/validate z sessionToken i email użytkownika; prawidłowy token kończy się sukcesem, a nieprawidłowy lub wygasły zwraca 401. Użyj /auth/me, gdy potrzebujesz profilu bieżącego użytkownika. Robienie tego na serwerze przy każdym chronionym żądaniu ma znaczenie, ponieważ podpisany token, którego nigdy nie weryfikujesz, niczego nie chroni.
Wygasanie jest częścią projektu. Gdy token wygaśnie, użytkownik loguje się ponownie, zamiast aplikacji po cichu próbującej go przedłużyć. Upewnij się, że Twoja aplikacja obsługuje ten kod 401 poprawnie, odsyłając użytkownika do logowania.
Krok 5: Obsłuż uwierzytelnianie dwuskładnikowe
Jeśli użytkownik włączył 2FA, /auth/login nie zwraca tokenu sesji. Zamiast tego zwraca requires2FA oraz tempToken. Twoja aplikacja prosi wtedy o drugi składnik i wymienia tempToken za pośrednictwem jednego z punktów końcowych weryfikacji /auth/2fa (kod TOTP, kod zapasowy lub OTP przesłany e-mailem). Dopiero ta wymiana daje prawdziwy token sesji, więc zadbaj o zapisanie właśnie jego, a nigdy tempToken.
Debugowanie tokenów za pomocą jwt.io
Gdy coś jest nie tak, najszybszym sposobem na sprawdzenie, co faktycznie zawiera token, jest jwt.io. Wklej token do jego debuggera, a zdekoduje nagłówek i ładunek, dzięki czemu sprawdzisz algorytm, deklarację sub i czas wygaśnięcia. Zwykle wystarcza to, aby wychwycić wygasły token, niewłaściwego użytkownika lub tempToken zapisany przez pomyłkę.
Z tego wszystkiego wynika jedno ostrzeżenie: token jest poświadczeniem. Traktuj działający token produkcyjny jako dane wrażliwe, podczas debugowania wybieraj konta testowe i unikaj wklejania prawdziwych tokenów do narzędzi, którym nie ufasz. Zdekodowanie tokenu to nie to samo co jego weryfikacja. Weryfikacja nadal odbywa się na Twoim serwerze przez /auth/validate.
Krok 6: Wyloguj użytkownika
Aby zakończyć sesję, wywołaj /auth/logout z sessionToken i email, a następnie usuń token z miejsca, w którym go przechowywałeś. Zmiana hasła działa podobnie, przez /auth/changePassword. Rejestrowanie zdarzeń uwierzytelniania po drodze daje przydatny ślad, jeśli coś pójdzie nie tak.
Lista kontrolna integracji JWT
- Klucz API znajduje się wyłącznie w konfiguracji po stronie serwera, nigdy w kodzie przeglądarki.
- Przed każdą rejestracją i logowaniem następuje świeże wywołanie
/auth/fooBar. - W ładunkach tokenów nie umieszcza się haseł ani sekretów; użytkowników identyfikuje się za pomocą
subi roli. - Token sesji jest przechowywany w ciasteczku HTTP-only lub innym magazynie kontrolowanym przez serwer.
- Każda chroniona trasa weryfikuje token przez
/auth/validateprzed wykonaniem jakiejkolwiek pracy. - Wygasłe lub nieprawidłowe tokeny (401) odsyłają użytkownika do logowania.
- Ścieżka 2FA zapisuje końcowy token sesji, a nie
tempToken. - Cały ruch korzysta z HTTPS, a tokeny nigdy nie są zapisywane w logach.
To cała pętla: uwierzytelnij się raz, noś podpisany token, weryfikuj go na serwerze i pozwól mu wygasnąć. Przeczytaj przewodnik na start, aby poznać pełną dokumentację punktów końcowych, lub zobacz, jak podchodzą do tego inne platformy. Gdy token wygląda podejrzanie, jwt.io pokaże, co jest w środku.