C# Academy · Lekcja

Struktura JWT i deklaracje

Poznaj nagłówek, ładunek i podpis.

Struktura JWT i deklaracje to bezpłatna lekcja C# Academy na CoddyKit. To lekcja 1 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej C# Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs C# Academy zawiera 4 lekcji w sumie.

Czym jest JWT

JSON Web Token (JWT) to zwarty, bezpieczny dla adresów URL format tokenu używany do bezpiecznego przesyłania claims między dwiema stronami. W ASP.NET Core jest to najczęstszy sposób uwierzytelniania bezstanowych interfejsów API.

JWT jest po prostu ciągiem złożonym z trzech części zakodowanych w Base64Url i połączonych kropkami: header.payload.signature.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0Iiwicm9sZSI6ImFkbWluIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Nagłówek

Nagłówek opisuje sposób podpisania tokenu. Jest niewielkim obiektem JSON, który jest kodowany w Base64Url i trafia do pierwszego segmentu.

alg określa algorytm podpisu, na przykład HS256 lub RS256, a typ to niemal zawsze JWT.

{
  "alg": "HS256",
  "typ": "JWT"
}

Ładunek

Ładunek zawiera claims — informacje dotyczące użytkownika i metadane tokenu. Jest to drugi segment.

Ważne: ładunek jest tylko kodowany, a nie szyfrowany. Każdy może go zdekodować, dlatego nigdy nie należy umieszczać w nim sekretów.

{
  "sub": "1234",
  "name": "Alice",
  "role": "admin",
  "exp": 1735689600
}

Podpis

Podpis gwarantuje, że token nie został zmodyfikowany. Serwer oblicza go na podstawie zakodowanego nagłówka, zakodowanego ładunku i tajnego klucza.

Jeśli ktoś zmieni choćby jeden znak ładunku, podpis przestanie pasować i walidacja się nie powiedzie.

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secretKey
)

Zarejestrowane claims

Niektóre nazwy claims są standaryzowane przez specyfikację JWT (RFC 7519). Używają krótkich, trzyznakowych kluczy:

iss — wystawca
sub — podmiot (identyfikator użytkownika)
aud — odbiorcy
exp — czas wygaśnięcia (sekundy czasu Unix)
nbf — ważny od
iat — wydany

{
  "iss": "https://api.myapp.com",
  "aud": "myapp-clients",
  "sub": "42",
  "exp": 1735689600,
  "iat": 1735686000
}

Niestandardowe claims

Oprócz zarejestrowanego zestawu można dodawać dowolne niestandardowe claims wymagane przez aplikację — role, uprawnienia, identyfikatory tenantów, adres e-mail i inne informacje.

Ładunek powinien być niewielki: każdy claim jest przesyłany przy każdym żądaniu.

{
  "sub": "42",
  "email": "alice@myapp.com",
  "role": "admin",
  "tenant_id": "acme",
  "permissions": ["orders:read", "orders:write"]
}

Claimy w ASP.NET Core

W .NET claimy są reprezentowane przez typ System.Security.Claims.Claim. Każdy claim to para typ / wartość.

Po zweryfikowaniu tokenu JWT ASP.NET Core zamienia każdy wpis payloadu na obiekt Claim w obiekcie ClaimsPrincipal użytkownika.

var claims = new List<Claim>
{
    new Claim(ClaimTypes.NameIdentifier, "42"),
    new Claim(ClaimTypes.Name, "Alice"),
    new Claim(ClaimTypes.Role, "admin"),
    new Claim("tenant_id", "acme")
};

ClaimsPrincipal i ClaimsIdentity

Uwierzytelniony użytkownik jest reprezentowany przez obiekt ClaimsPrincipal, który opakowuje co najmniej jeden obiekt ClaimsIdentity, z których każdy przechowuje zestaw claimów.

W kontrolerze dostęp do niego uzyskuje się przez User.

// Inside a controller action
var userId = User.FindFirstValue(ClaimTypes.NameIdentifier);
bool isAdmin = User.IsInRole("admin");
string? tenant = User.FindFirst("tenant_id")?.Value;

Mapowanie typów claimów

Domyślnie handler JWT mapuje krótkie klucze JWT na długie typy claimów w formacie URI (na przykład sub staje się ClaimTypes.NameIdentifier).

Aby zachować oryginalne krótkie nazwy, należy jednokrotnie wyłączyć mapowanie przychodzące podczas uruchamiania aplikacji.

JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear();
// Now User.FindFirst("sub") returns the raw 'sub' claim

Dlaczego nie użyć po prostu ciasteczka sesyjnego?

Tokeny JWT są samowystarczalne: serwer może je zweryfikować, korzystając wyłącznie z klucza podpisującego, bez odpytywania bazy danych ani serwerowego magazynu sesji.

Dzięki temu doskonale nadają się do skalowanych horyzontalnie interfejsów API i mikrousług, w których każdy węzeł może zweryfikować ten sam token.

// Client sends the token on every request:
// Authorization: Bearer eyJhbGciOiJIUzI1Ni...

Kompromis: unieważnianie

Ponieważ token JWT jest samowystarczalny i zaufany aż do wygaśnięcia, nie można łatwo unieważnić go przed upływem czasu określonego przez exp.

Typowym rozwiązaniem jest używanie krótkotrwałych tokenów dostępu i łączenie ich z tokenami odświeżającymi (omówionymi w dalszej części tego kursu).

// Short-lived access token
exp = iat + 15 * 60;  // 15 minutes

Szybkie sprawdzenie

Proszę sprawdzić swoją znajomość struktury JWT.

Podsumowanie

Poznano budowę tokenu JWT oraz sposób działania claimów w ASP.NET Core:

JWT ma postać header.payload.signature, a każda część jest zakodowana w Base64Url.
Payload zawiera zarejestrowane i niestandardowe claime — są one zakodowane, ale niezaszyfrowane.
Podpis gwarantuje integralność przy użyciu sekretu lub pary kluczy.
.NET zamienia claime na obiekt ClaimsPrincipal, który można odczytać za pośrednictwem User.

Następnie należy skonfigurować ASP.NET Core tak, aby weryfikował te tokeny.

Często zadawane pytania

Czy lekcja „Struktura JWT i deklaracje” jest bezpłatna?

Tak — pełny tekst „Struktura JWT i deklaracje” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu C# Academy, przejdź na CoddyKit PRO. Kurs C# Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Struktura JWT i deklaracje”?

Poznaj nagłówek, ładunek i podpis. Ćwiczysz C# Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć C# Academy?

Nie wymagamy żadnego doświadczenia. C# Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 1 z 4.

Ile czasu zajmuje lekcja „Struktura JWT i deklaracje”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji C# Academy?

Tak. Każda lekcja C# Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

Struktura JWT i deklaracje
Konfigurowanie uwierzytelniania JWT Bearer
Wystawianie tokenów
Tokeny odświeżania i wygaśnięcie

← Powrót do C# Academy