Utwórz podpisany JSON Web Token (JWT)

Czym jest JWT Builder?

JWT Builder to narzędzie online, które produkuje podpisany JSON Web Token (JWT) na podstawie payloadu JSON i sekretu HMAC. Jest skierowane do programistów, którzy muszą szybko wygenerować testowy token, aby zweryfikować zachowanie API, symulować uwierzytelnioną sesję w Postman lub odtworzyć błąd związany z wygaśnięciem lub zakresem tokenu.

W przeciwieństwie do naszego dekodera JWT, który ogranicza się do czytania istniejącego tokenu, JWT Builder tworzy kompletny token: buduje nagłówek, koduje payload, oblicza podpis HMAC i składa wszystko w formacie kompaktowym header.payload.signature oczekiwanym przez wszystkie biblioteki JWT na rynku.

Dlaczego generować JWT?

Builder JWT nie ma na celu emisji tokenów produkcyjnych. To przede wszystkim narzędzie do rozwoju i testów. Oto najczęstsze scenariusze:

• Testy integracyjne: produkcja przewidywalnych JWT do sterowania testami E2E, które uderzają w chronione endpointy bez zależności od prawdziwego dostawcy tożsamości.
• Mocki API: tymczasowe zastąpienie wywołania do IdP JWT podpisanym lokalnie tym samym testowym sekretem.
• Rozwój lokalny: połączenie z własnym backendem przez ręczne wygenerowanie tokenu zawierającego pożądane claims, bez przechodzenia przez cały flow OAuth2.
• Demonstracje: ilustrowanie ścieżki uwierzytelnienia lub workflow opartego na uprawnieniach bez konieczności posiadania prawdziwego IdP pod ręką.
• Odtwarzanie błędów: tworzenie tokenu wygasłego, tokenu z niepoprawnym aud, tokenu bez niektórych claims, do testowania ścieżek błędu twojego API.
• Debugowanie niestandardowego parsera: wstrzykiwanie specjalnie skonstruowanych JWT do testowania domowego parsera.

Kompozycja JWT

Podpisany JWT składa się z trzech segmentów oddzielonych kropką, z których każdy jest zakodowany w Base64URL (wariancie Base64 bez paddingu i z -/_ zamiast +//):

• Header: obiekt JSON, który opisuje algorytm podpisu i typ tokenu, na przykład {"alg":"HS256","typ":"JWT"}. JWT Builder generuje go automatycznie z wybranego algorytmu.
• Payload: dowolny obiekt JSON zawierający claims tokenu (podmiot, uprawnienia, daty wygaśnięcia). To część, którą dostarczasz.
• Signature: HMAC-SHA obliczony na konkatenacji base64url(header) + "." + base64url(payload) twoim sekretnym kluczem. To ona gwarantuje integralność tokenu.

Szczegółowe przypadki użycia

• API mock do testów E2E: twój zestaw testów Cypress lub Playwright musi wywołać API wymagające Authorization: Bearer .... Zamiast orkiestrować pełen login przy każdym teście, podpisujemy JWT na bieżąco wspólnym sekretem i wstrzykujemy go do nagłówka.
• Demonstracja SSO: prezentacja ścieżki uwierzytelnienia federacyjnego bez zależności od IdP online.
• Fixture testu: generowanie deterministycznego JWT z znanego payloadu do służenia jako stabilna fixture w testach jednostkowych.
• Diagnostyka niestandardowego parsera: testowanie domowego parsera JWT tokenami celowo minimalnymi lub celowo dziwacznymi (brakujące claims, nieoczekiwane typy).
• Nauka: konkretne zrozumienie, jak budowany jest JWT, modyfikując payload i obserwując zmianę podpisu.

Obsługiwane algorytmy: HS256, HS384, HS512

Nasze narzędzie obsługuje trzy standardowe algorytmy HMAC specyfikacji JWT (RFC 7519):

• HS256: HMAC z SHA-256. Podpis 32 bajty. Najczęściej używany w praktyce, dobry kompromis między szybkością a solidnością kryptograficzną. Zalecany domyślnie.
• HS384: HMAC z SHA-384. Podpis 48 bajtów. Odpowiedni dla kontekstów wymagających większego marginesu bezpieczeństwa.
• HS512: HMAC z SHA-512. Podpis 64 bajty. Najbardziej solidny, kosztem nieco większego tokenu.

HMAC czy RSA?

Algorytmy HS* są symetryczne: ten sam klucz służy do podpisywania i weryfikacji. Jest to proste i szybkie, ale oznacza, że każda usługa zdolna do weryfikacji tokenu jest również zdolna do jego emitowania. Jeśli musisz oddzielić te dwie role (jeden emitent, wielu konsumentów), zwróć się do algorytmów RS256/RS384/RS512 (RSA, asymetryczne), które możesz weryfikować naszym JWT verifier.

Bezpieczeństwo: ochrona swojego sekretu

Bezpieczeństwo JWT podpisanego w HMAC opiera się całkowicie na poufności sekretu. Kilka podstawowych zasad:

• Używaj długiego i losowego sekretu. RFC 7518 zaleca minimum wielkość wyjścia algorytmu (32 bajty dla HS256, 48 dla HS384, 64 dla HS512). Ludzkie hasło typu azerty123 jest banalnie atakowalne przez brute force offline.
• Nigdy nie podpisuj JWT po stronie klienta. Sekret znalazłby się w kodzie JavaScript dystrybuowanym do przeglądarki, narażonym na każdego użytkownika. Podpis musi zawsze pozostać po stronie serwera.
• Przechowuj sekret w zmiennej środowiskowej (np. JWT_SECRET), nigdy w repozytorium Git. Pomyśl o użyciu skarbca, takiego jak HashiCorp Vault, AWS Secrets Manager lub Symfony Secrets w zależności od stacku.
• Regularnie rotuj sekret (key rotation), zwłaszcza po incydencie lub odejściu osoby mającej dostęp do konfiguracji.
• JWT Builder jest przeznaczony do testów i nauki. Do produkcji użyj biblioteki JWT swojego frameworka (lcobucci/jwt, firebase/php-jwt, jose-php).

Dobre praktyki claims

Payload to wolny obiekt JSON, ale RFC 7519 definiuje zestaw registered claims, które biblioteki JWT umieją interpretować. Dołączenie odpowiednich claims czyni twój token przenośnym i unika subtelnych błędów:

• iss (issuer): identyfikator emitenta, na przykład "https://api.example.com".
• sub (subject): identyfikator osoby lub podmiotu, którego dotyczy, często ID użytkownika.
• aud (audience): dla kogo przeznaczony jest token, aby zapobiec ponownemu użyciu tokenu w innym API.
• exp (expiration time): timestamp Unix, po którym token jest nieważny. Zawsze dołączaj, nawet dla testowego tokenu: token bez wygaśnięcia to zły nawyk trudny do skorygowania później.
• nbf (not before): timestamp, przed którym token nie jest jeszcze ważny. Przydatny do wstępnego emitowania tokenu aktywowalnego później.
• iat (issued at): timestamp emisji, przydatny do logowania i unieważniania.
• jti (JWT ID): unikalny identyfikator tokenu, niezbędny do idempotencji i implementacji listy unieważnień.

Przykład typowego payloadu

{
  "iss": "https://api.example.com",
  "sub": "user-12345",
  "aud": "mobile-app",
  "iat": 1714723200,
  "exp": 1714726800,
  "jti": "9f2d6b1e-2c4a-4f8a-9c3a-87a2b8a4b7e1",
  "scope": "read:profile write:profile"
}

Jak korzystać z narzędzia

1. Wprowadź payload jako prawidłowy JSON. To obiekt, więc zaczyna się od { i kończy się na }.
2. Wskaż sekret HMAC. Wybierz długi i losowy ciąg dla tokenów produkcyjnych.
3. Wybierz algorytm: HS256 domyślnie, HS384 lub HS512 zgodnie z potrzebami.
4. Kliknij utwórz. Podpisany JWT pojawi się, gotowy do wklejenia w nagłówek Authorization: Bearer ....
5. Następnie możesz zweryfikować token tym samym sekretem, aby potwierdzić spójność round-trip, lub zdekodować go, aby ponownie odczytać jego zawartość.

Najczęściej zadawane pytania

Przykładowe zapytanie

curl -X POST https://cdrn.fr/api/v1/tools/jwt-builder/execute \
  -H "Content-Type: application/json" \
  -d '{"payload":"...","secret":"...","algorithm":"HS256"}'

Schemat wejściowy

Punkty końcowe

• GET https://cdrn.fr/api/v1/tools - lista wszystkich dostępnych narzędzi
• GET https://cdrn.fr/api/v1/tools/jwt-builder - zwraca schemat dla tego narzędzia
• POST https://cdrn.fr/api/v1/tools/jwt-builder/execute - uruchamia to narzędzie z payloadem JSON