Czym jest JWT? Przejrzysty przewodnik po JSON Web Tokenach

JWT w prostych słowach

JWT (JSON Web Token) to zwarty, bezpieczny dla URL-a ciąg znaków, który reprezentuje pewien zestaw informacji (zazwyczaj o użytkowniku lub sesji) w formie, którą można przekazywać między systemami. Często zobaczysz go jako długą wartość zaczynającą się od czegoś w stylu eyJ..., wysyłaną w nagłówku HTTP, np. Authorization: Bearer \u003ctoken\u003e.

Po co w ogóle token?

Tradycyjne logowania często opierają się na sesjach po stronie serwera: po zalogowaniu serwer przechowuje dane sesji i daje przeglądarce cookie z ID sesji. Każde żądanie zawiera to cookie i serwer odczytuje sesję.

W uwierzytelnianiu opartym na tokenach serwer może uniknąć przechowywania stanu sesji dla każdego żądania. Zamiast tego klient trzyma token (np. JWT) i dołącza go do wywołań API. To popularne w przypadku API, ponieważ:

• dobrze działa w wielu serwisach (API gateway, mikroserwisy)
• pasuje do aplikacji mobilnych i SPA, które wywołują API bezpośrednio
• redukuje potrzebę współdzielenia pamięci sesji między serwerami

Ważna uwaga: „bezstanowość” nie znaczy „brak żadnych kontroli po stronie serwera”. W praktyce wiele systemów nadal weryfikuje tokeny względem statusu użytkownika, rotacji kluczy lub mechanizmów unieważniania.

Uwierzytelnianie a autoryzacja (po ludzku)

• Uwierzytelnianie odpowiada na pytanie: Kim jesteś? (logujesz się i udowadniasz tożsamość).
• Autoryzacja odpowiada na pytanie: Co możesz zrobić? (możesz czytać faktury, edytować projekty, wejść na strony admina itp.).

JWT często zawierają dowód uwierzytelnienia (jesteś zalogowany) oraz podpowiedzi autoryzacyjne (role, uprawnienia, scope) — ale serwer nadal powinien egzekwować reguły autoryzacji.

Gdzie pojawiają się JWT

JWT często używa się jako access tokenów w:

• API webowych
• SPA
• aplikacjach mobilnych
• systemach wykorzystujących OAuth 2.0 lub OpenID Connect (OIDC)

Budowa JWT: header, payload i signature

JWT to zwarty ciąg złożony z trzech części, każda zakodowana Base64URL i oddzielona kropkami:

header.payload.signature

Przykład (ocenzurowany):

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiaWF0IjoxNzAwMDAwMDAwfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c…

1) Header

Header opisuje, jak token został utworzony — najważniejszym polem jest algorytm podpisu (np. HS256, RS256/ES256) i typ tokena.

Częste pola:

• typ: często "JWT" (w praktyce często ignorowane)
• alg: użyty algorytm podpisu
• kid: identyfikator klucza pomagający weryfikatorowi wybrać właściwy klucz podczas rotacji

Uwaga bezpieczeństwa: nie ufaj headerowi bez sprawdzenia. Wprowadź allowlistę algorytmów, których faktycznie używasz, i nie akceptuj alg: "none".

2) Payload

Payload zawiera „claims” (pola) o użytkowniku i kontekście tokena: dla kogo jest, kto go wystawił i kiedy wygasa.

Ważne: JWT nie są domyślnie szyfrowane. Kodowanie Base64URL sprawia, że token jest bezpieczny w URL, ale nie ukrywa danych. Każdy, kto ma token, może odszyfrować header i payload.

Dlatego unikaj wkładania sekretów (haseł, kluczy API) lub wrażliwych danych osobowych do JWT.

3) Signature

Signature powstaje przez podpisanie header + payload kluczem:

• HS256: podpis i weryfikacja za pomocą wspólnego sekretu
• RS256/ES256: prywatny klucz podpisuje; publiczny klucz weryfikuje

Podpis zapewnia integralność: pozwala serwerowi sprawdzić, że token nie został zmieniony i został wydany przez zaufanego podpisującego. Nie zapewnia poufności.

Rozmiar tokena

Ponieważ JWT zawiera header i payload przy każdym żądaniu, większe tokeny to więcej transferu i narzutów. Trzymaj claims oszczędnie i preferuj identyfikatory zamiast dużych danych.

Payload i roszczenia: co możesz (i czego nie powinieneś) przechowywać

Claims zwykle dzielą się na dwie grupy: zarejestrowane (standardowe nazwy) i własne (pola aplikacji).

Popularne zarejestrowane claims

• iss (issuer): kto stworzył token
• sub (subject): o kim jest token (zazwyczaj ID użytkownika)
• aud (audience): dla kogo jest token (np. konkretne API)
• exp (expiration time): kiedy token powinien przestać być akceptowany
• iat (issued at): kiedy token został utworzony
• nbf (not before): token nie powinien być akceptowany przed tym czasem

Własne claims: trzymaj je małe

Dołącz tylko to, czego serwis odbierający naprawdę potrzebuje do podjęcia decyzji autoryzacyjnej.

Dobre przykłady:

• stabilny wewnętrzny identyfikator użytkownika (user_id)
• niewielki zestaw ról/uprawnień (tylko jeśli potrafisz je utrzymywać na bieżąco)
• ID najemcy/organizacji w aplikacjach multi-tenant

Unikaj „wygodnych” claims, które duplikują dużo danych profilu. Zwiększają rozmiar tokena, szybko się starzeją i powiększają skutki wycieku.

Czego NIGDY nie umieszczać w payloadzie JWT

Ponieważ payload jest czytelny, nie przechowuj tam:

• haseł, kluczy API, refresh tokenów ani innych sekretów
• danych płatniczych, numerów dokumentów ani wrażliwych danych osobowych
• niczego, czego nie chciałbyś zobaczyć w przeglądarce, proxy lub logach

Jeśli potrzebujesz wrażliwych informacji, trzymaj je po stronie serwera i w tokenie umieść tylko referencję (np. ID) — lub użyj szyfrowanego formatu tokena (JWE), gdy to odpowiednie.

Jak działa podpis (i co gwarantuje)

Podpisanie to nie szyfrowanie.

• Podpis jest jak zapieczętowany list: każdy może go odczytać, ale można sprawdzić, czy został zmieniony.
• Szyfrowanie jest jak zamknięcie listu w skrzyni z zamkiem: tylko ktoś z kluczem może odczytać.

Kiedy JWT jest wystawiany, serwer podpisuje zakodowany header + payload. Gdy token jest przedstawiony później, serwer przelicza podpis i porównuje go. Jeśli ktoś zmieni choćby jeden znak (np. "role":"user" na "role":"admin"), weryfikacja nie przejdzie i token zostanie odrzucony.

JWT vs OAuth, OpenID Connect i typy tokenów

JWT to format tokena. OAuth 2.0 i OpenID Connect (OIDC) to protokoły, które opisują, jak aplikacje żądają, wydają i używają tokenów.

OAuth 2.0 i access/refresh tokeny

OAuth 2.0 dotyczy głównie autoryzacji: pozwalania aplikacji na dostęp do API w imieniu użytkownika bez przekazywania hasła.

• Access token: przedstawiany API, by udowodnić uprawnienia; może być JWT lub tokenem opaque
• Refresh token: dłużej żyjący token używany do uzyskania nowych access tokenów

Access tokeny zwykle są krótkotrwałe (minuty). Krótkie życie ogranicza szkody w razie wycieku.

OpenID Connect (OIDC) i ID tokeny

OIDC dodaje uwierzytelnianie (kim jest użytkownik) do OAuth 2.0 i wprowadza ID token, który jest zwykle JWT.

• ID token: dla aplikacji klienckiej do potwierdzenia tożsamości użytkownika
• Access token: dla API do autoryzacji żądań

Zasada: nie używaj ID tokena do wywołań API.

Jeśli chcesz więcej kontekstu o praktycznych przepływach, zobacz /blog/jwt-authentication-flow.

Typowy przepływ uwierzytelniania JWT

Przykładowy flow wygląda tak:

1) Logowanie

Użytkownik loguje się (email/hasło, SSO itp.). Jeśli logowanie zakończy się sukcesem, serwer tworzy JWT (często access token) z niezbędnymi roszczeniami jak subject i expiration.

2) Wydanie tokena

Serwer podpisuje token i zwraca go klientowi (aplikacja web, mobilna lub inny serwis).

3) Wywołania API

Dla chronionych endpointów klient dołącza JWT w nagłówku Authorization:

Authorization: Bearer \u003cJWT\u003e

4) Weryfikacja

Zanim API obsłuży żądanie, zazwyczaj sprawdza:

• podpis (integralność + zaufany issuer)
• exp (czy nie wygasł)
• iss (oczekiwany issuer)
• aud (czy token jest przeznaczony dla tego API)

Jeśli wszystkie kontrole przejdą, API traktuje użytkownika jako uwierzytelnionego i stosuje reguły autoryzacji (np. uprawnienia do poziomu rekordu).

5) Krótka uwaga o dryfie zegarów

Ponieważ zegary systemowe driftują, wiele systemów dopuszcza niewielki clock skew przy weryfikacji roszczeń czasowych jak exp (i czasem nbf). Trzymaj ten przesunięcie małe, aby nie przedłużać niezamierzenie ważności tokena.

Gdzie bezpiecznie przechowywać JWT

Wybór miejsca przechowywania determinuje, co atakujący może ukraść i jak łatwo może odtworzyć żądanie przy użyciu tokena.

Aplikacje web: pamięć vs localStorage vs cookies

Przechowywanie w pamięci (często rekomendowane dla SPA) trzyma access token w stanie JS. Czyszczony po odświeżeniu strony, zmniejsza ryzyko „kradzieży później”, ale błąd XSS nadal może go odczytać podczas działania strony. Łącz to z krótkimi access tokenami i mechanizmem odnawiania.

localStorage/sessionStorage są wygodne, ale ryzykowne: każde XSS pozwala na exfiltrację tokenów z pamięci przeglądarki. Jeśli ich używasz, zapobieganie XSS jest obowiązkowe (CSP, escapowanie wyjścia, higiena zależności) i trzymaj tokeny krótko żyjące.

Bezpieczne cookies (często najbezpieczniejszy domyślny wybór dla webu) przechowują tokeny w ciasteczku HttpOnly, tak że JavaScript nie może ich odczytać — zmniejsza to wpływ kradzieży tokena przez XSS. Wadą jest ryzyko CSRF, bo przeglądarki automatycznie dołączają cookies.

Jeśli używasz cookies, ustaw:

• HttpOnly
• Secure (tylko HTTPS)
• SameSite=Lax lub SameSite=Strict (niektóre cross-site flowy mogą wymagać SameSite=None; Secure)

Rozważ także tokeny CSRF dla żądań zmieniających stan.

Aplikacje mobilne: używaj bezpiecznego magazynu OS

Na iOS/Android przechowuj tokeny w bezpiecznym magazynie systemowym (Keychain / Keystore-backed storage). Unikaj zwykłych plików lub preferencji. Jeśli model zagrożeń obejmuje urządzenia z rootem/jailbreakiem, zakładaj, że ekstrakcja jest możliwa i polegaj na krótkotrwałych tokenach oraz kontrolach po stronie serwera.

Zasada najmniejszych uprawnień

Ogranicz możliwości tokena: używaj minimalnych scope'ów/claimów, trzymaj access tokeny krótkotrwałe i unikaj osadzania wrażliwych danych.

Typowe pułapki bezpieczeństwa JWT

JWT są wygodne, ale wiele incydentów wynika z przewidywalnych błędów. Traktuj JWT jak gotówkę: kto go zdobędzie, zwykle może go użyć.

1) Zbyt długie wygasanie

Jeśli token ważny jest dni lub tygodnie, wyciek daje atakującemu cały ten okres. Preferuj krótkotrwałe access tokeny (minuty) i odnawiaj je bezpiecznym mechanizmem. Jeśli potrzebujesz „zapamiętaj mnie”, zrób to za pomocą refresh tokenów i kontroli po stronie serwera.

2) Pomijanie sprawdzeń issuer i audience

Sam ważny podpis to za mało. Weryfikuj iss i aud, oraz waliduj roszczenia czasowe jak exp i nbf.

3) Ufanie zdekodowanemu payloadowi

Dekodowanie to nie weryfikacja. Zawsze weryfikuj podpis po stronie serwera i egzekwuj uprawnienia po stronie serwera.

4) Zamieszanie z algorytmami i kluczami

• Nie akceptuj dowolnego algorytmu, który deklaruje token. Stosuj allowlistę.
• Nie mieszaj kluczy symetrycznych (HS256) z kluczami publiczno-prywatnymi (RS256/ES256).
• Minimalizuj blast radius przez rozdzielenie kluczy między środowiskami i ich rotację.

5) Wycieki tokenów przez URL, logi i referrery

Unikaj umieszczania JWT w parametrach zapytania. Mogą trafić do historii przeglądarki, logów serwerów, narzędzi analitycznych i nagłówków referer.

Używaj Authorization: Bearer ... zamiast tego.

6) Brak planu rotacji kluczy i unieważniania

Zakładaj, że klucze i tokeny mogą wyciec. Rotuj klucze podpisujące, używaj kid by wspierać płynną rotację i miej strategię unieważniania (krótkie czasy życia + możliwość dezaktywacji kont/sesji). Dla wskazówek odnośnie przechowywania tokenów zobacz /blog/where-to-store-jwts-safely.

Kiedy używać JWT (a kiedy nie)

JWT są użyteczne, ale nie zawsze najlepsze. Pytanie brzmi: czy skorzystasz na samodzielnym tokenie, który można zweryfikować bez odpytywania bazy danych przy każdym żądaniu.

Dobre zastosowania JWT

• Bezustanowe API w skali: lokalna weryfikacja (podpis + expiry) bez odpytywania sesji przy każdym żądaniu
• Wiele usług / mikroserwisy: wspólna weryfikacja i publiczne klucze
• SPA i aplikacje mobilne: klienci wywołują API bezpośrednio
• Krótkożyjące access tokeny: mniejsze skutki kradzieży

Kiedy JWT to słaby wybór

• Wymagana jest natychmiastowa unieważnialność: sesje po stronie serwera są prostsze, jeśli potrzebujesz „wyloguj wszędzie teraz” bez dodatkowej infrastruktury
• Musisz przechowywać wrażliwe dane: typowe JWT są podpisane, nie zaszyfrowane
• Długożyjące tokeny: są wysokowartościowe i warto je ukraść

Kiedy prostsze ciasteczka sesyjne są lepsze

Dla tradycyjnych aplikacji renderowanych po stronie serwera, gdzie proste unieważnianie ma znaczenie, sesje po stronie serwera z HttpOnly cookies często są prostszym i bezpieczniejszym wyborem.

Szybka lista kontrolna decyzji

Wybierz JWT, jeśli potrzebujesz bezstanowej weryfikacji między usługami i możesz trzymać tokeny krótkotrwałe.

Unikaj JWT, jeśli potrzebujesz natychmiastowego unieważniania, planujesz przechowywać wrażliwe dane w tokenie, lub możesz użyć ciasteczek sesyjnych bez problemów.

Praktyczna lista kontrolna i FAQ

Lista weryfikacji (co sprawdzać za każdym razem)

1. Podpis jest ważny

Weryfikuj używając właściwego klucza i oczekiwanego algorytmu. Odrzucaj nieprawidłowe podpisy — bez wyjątków.

2. exp (wygaśnięcie)

Upewnij się, że token nie wygasł.

3. nbf (not before)

Jeśli obecne, upewnij się, że token nie jest używany zbyt wcześnie.

4. aud (audience)

Potwierdź, że token był przeznaczony dla Twojego API/serwisu.

5. iss (issuer)

Potwierdź, że token pochodzi od oczekiwanego issuer.

6. Kontrole sanitarne (zalecane)

Waliduj format tokena, egzekwuj maksymalny rozmiar i odrzucaj nieoczekiwane typy roszczeń, aby zmniejszyć liczbę błędów brzegowych.

Wybór HS256 vs RS256/ES256

• HS256 (klucz symetryczny): jeden wspólny sekret podpisuje i weryfikuje.

  • Dobre do: jednej aplikacji/API kontrolowanej przez jeden zespół.
  • Uwaga: każdy weryfikator mający sekret może też wystawiać tokeny.

• RS256 / ES256 (klucze asymetryczne): prywatny klucz podpisuje; publiczny weryfikuje.

  • Dobre do: wielu serwisów weryfikujących tokeny; dystrybucji klucza publicznego bez umożliwienia podpisywania.
  • Uwaga operacyjna: rotacja jest często bezpieczniejsza, bo tylko podpisujący trzyma prywatny klucz.

Zasada: jeśli więcej niż jeden niezależny system musi weryfikować tokeny (albo nie ufasz każdemu weryfikatorowi), preferuj RS256/ES256.

Monitorowanie i logowanie (bez wycieków tokenów)

• Nie loguj surowych tokenów (nagłówków, ciasteczek, parametrów query).
• Jeśli potrzebujesz korelacji, loguj odcisk tokena (np. hash) lub bezpieczne metadane (iss, aud, identyfikator użytkownika tylko jeśli polityka na to pozwala).
• Obserwuj anomalie: nieudane podpisy, skoki w liczbie wygasłych tokenów, nietypowe audience/issuer i podejrzane wzorce odnawiania.

FAQ

Czy JWT są szyfrowane?

Nie domyślnie. Większość JWT jest podpisana, nie szyfrowana, co oznacza, że zawartość można odczytać przez każdego, kto ma token. Użyj JWE lub trzymaj wrażliwe dane poza JWT.

Czy mogę unieważnić JWT?

Niełatwo, jeśli polegasz wyłącznie na samodzielnych access tokenach. Typowe podejścia to krótkotrwałe access tokeny, deny-listy dla wysokiego ryzyka lub refresh tokeny z rotacją.

Jak długo powinno trwać exp?

Tak krótko, jak na to pozwala UX i architektura. Wiele API używa minut dla access tokenów i łączy to z refresh tokenami dla dłuższych sesji.

Szybsze budowanie aplikacji chronionych JWT z Koder.ai

Jeśli implementujesz uwierzytelnianie JWT w nowym API lub SPA, dużo pracy jest powtarzalne: podłączanie middleware, walidacja iss/aud/exp, ustawianie flag ciasteczek i wyłączanie logowania tokenów.

Z Koder.ai możesz szybko stworzyć aplikację web (React), serwisy backendowe (Go + PostgreSQL) lub aplikację mobilną Flutter przez chatowy workflow — potem iterować w trybie planowania, używać snapshotów i rollbacku przy dopracowywaniu bezpieczeństwa oraz eksportować kod źródłowy, gdy jesteś gotowy. To praktyczny sposób przyspieszający budowę przepływów autoryzacji JWT, zachowując kontrolę nad logiką weryfikacji, strategią rotacji kluczy i ustawieniami wdrożenia/hostingu (w tym niestandardowe domeny).