Budowa JWT: nagłówek, ładunek i podpis

JSON Web Token (JWT) to kompaktowy, bezpieczny dla adresów URL format tokenu zdefiniowany w RFC 7519. Koduje claims (twierdzenia dotyczące podmiotu) i podpis kryptograficzny w pojedynczym ciągu znaków, umożliwiając bezstanowe uwierzytelnianie.

JWT ma postać: base64url(header).base64url(payload).base64url(signature). Kropka oddziela poszczególne części. Nagłówek i payload są czytelne (base64url, a nie zaszyfrowane). Tylko podpis ma charakter kryptograficzny.

Nagłówek jest obiektem JSON: {"alg":"HS256","typ":"JWT"}. alg określa algorytm podpisywania (HS256, RS256, ES256, none). typ zawsze ma wartość "JWT". Dodatkowe nagłówki obejmują kid (identyfikator klucza) używany do wyboru klucza.

Standardowe zarejestrowane claims: iss (wystawca), sub (podmiot), aud (odbiorcy), exp (znacznik czasu wygaśnięcia w systemie Unix), nbf (ważny od), iat (wystawiony o), jti (identyfikator JWT używany do unieważniania). Claims niestandardowe to dowolne dodatkowe pary klucz-wartość.

import base64, json token = "eyJ..." parts = token.split(".") header = json.loads(base64.urlsafe_b64decode(parts[0]+"==")) payload = json.loads(base64.urlsafe_b64decode(parts[1]+"==")) print(header, payload)

Dla HS256: HMAC-SHA256(base64url(header)+"."+base64url(payload), secret). Odbiorca oblicza tę wartość ponownie i porównuje ją z częścią zawierającą podpis. Jeśli wartości są zgodne, a token nie wygasł, token jest prawidłowy.

Dla RS256 klucz prywatny podpisuje ciąg header.payload za pomocą RSA-SHA256. Każda strona posiadająca klucz publiczny może przeprowadzić weryfikację bez klucza prywatnego. Klucze publiczne są rozpowszechniane za pośrednictwem punktów końcowych JWKS (JSON Web Key Set), np. /.well-known/jwks.json.

Base64url zastępuje znak + znakiem - oraz / znakiem _, a także pomija dopełnienie =. Dzięki temu JWT są bezpieczne w adresach URL, nagłówkach HTTP i ciasteczkach bez kodowania procentowego. Surowe bajty nadal nie są szyfrowane — są tylko zakodowane.

Payload JWT jest widoczny dla każdego, kto zdekoduje go za pomocą base64url. Nie należy umieszczać sekretów (haseł, numerów SSN) w payloadzie JWT, chyba że używany jest JWE (JSON Web Encryption) z algorytmem "enc" zapewniającym rzeczywiste szyfrowanie.

Wartość exp należy ustawić na krótki czas (15–60 minut w przypadku tokenów dostępu). Długotrwałe JWT zwiększają ryzyko — jeśli zostaną skradzione, pozostają ważne aż do wygaśnięcia. Należy używać bezpiecznie przechowywanych tokenów odświeżających do wydawania nowych tokenów dostępu o krótkim czasie życia.

Dostawcy uwierzytelniania (Auth0, Keycloak, Google) publikują adres URL JWKS. Weryfikator pobiera klucze publiczne według kid, buforuje je i weryfikuje podpisy bez kontaktowania się z wystawcą przy każdym żądaniu. Rotacja kluczy aktualizuje punkt końcowy JWKS.

JWT składa się z trzech zakodowanych w base64url części JSON: nagłówka (algorytm), payloadu (claims) i podpisu. Payload jest czytelny — nie jest szyfrowany. Następnie: wybór między HS256 i RS256.