Kurs NestJS · Moduł 4: Uwierzytelnianie

JWT Tokens - rzymskie przepustki

5 min czytania ·
W tej lekcji6

Legionista podał hasło przy bramie i został wpuszczony. Za godzinę wraca po zaopatrzenie - i co, znowu ma podawać hasło? A przy trzeciej bramie? Sprawdzanie hasła przy każdym kroku oznacza, że serwer musi przy każdym żądaniu sięgać do bazy po użytkownika. Setki razy na minutę, po to samo.

Rzymianie wydawali w takich razach przepustkę: dokument z wypisanymi uprawnieniami i pieczęcią, którą każdy strażnik potrafi rozpoznać. Wartownik nie biegnie do archiwum - patrzy na pieczęć i wie, że dokument jest prawdziwy. W sieci ta przepustka nazywa się JWT, czyli JSON Web Token.

Trzy części przepustki

Token JWT wygląda jak ciąg znaków przedzielony dwiema kropkami. Te kropki nie są przypadkowe - dzielą go na trzy części, zawsze w tej samej kolejności:

eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOjQyLCJyb2xlIjoiY2VudHVyaW9uIn0.dBjftJeZ4CVP
   <-- Header -->      <----- Payload ----->                  <- Signature ->

Header mówi, jakim algorytmem podpisano dokument. Payload to treść przepustki - dane o legioniście, zwane claims: jego identyfikator, rola, czas wygaśnięcia. Signature to pieczęć: wynik podpisania dwóch pierwszych części tajnym kluczem serwera.

Teraz najważniejsze i najczęściej mylone: payload jest zakodowany, ale nie zaszyfrowany. Każdy, kto przechwyci token, odczyta jego treść - to zwykły Base64, nie tajemnica. Pieczęć nie ukrywa danych, tylko dowodzi, że nikt ich nie podmienił, bo bez tajnego klucza nie da się jej podrobić. Wniosek praktyczny jest jeden: do payloadu nigdy nie wkładaj hasła ani danych wrażliwych.

Konfiguracja - wydawanie przepustek

Zdolność wydawania przepustek dodajemy przez moduł:

JwtModule.registerAsync({
  imports: [ConfigModule],
  inject: [ConfigService],
  useFactory: (configService: ConfigService) => ({
    secret: configService.get('JWT_SECRET'),
    signOptions: {
      expiresIn: '24h',
      issuer: 'LegionaryFleet',
    },
  }),
});

secret to tajny klucz, którym serwer pieczętuje tokeny i którym je potem weryfikuje. Czytamy go przez ConfigService ze zmiennej środowiskowej, w pliku .env zapisanej jako JWT_SECRET=super-secret-key - nazwa, znak równości, wartość, bez cudzysłowów i spacji. Klucz wpisany w kod trafiłby do repozytorium, a stamtąd w cudze ręce; kto ma klucz, może wystawić sobie przepustkę centuriona.

Używamy registerAsync zamiast zwykłego register, bo wartość klucza nie jest znana w chwili pisania kodu - trzeba ją najpierw odczytać z konfiguracji. Stąd useFactory: funkcja, którą NestJS wywoła, gdy ConfigService będzie już dostępny.

W signOptions opisujemy samą przepustkę. expiresIn: '24h' to jej czas życia - po dobie dokument traci ważność i legionista musi zalogować się ponownie. To celowe ograniczenie: gdyby token wyciekł, złodziej ma tylko tyle czasu. issuer to wystawca, zapisywany w payloadzie.

Kształt przepustki

Warto opisać typem, co dokładnie wkładamy do payloadu:

export interface JwtPayload {
  sub: number;
  username: string;
  email: string;
  role: string;
  iat: number;
  exp: number;
}

Trzy z tych nazw są skrótami ustalonymi w standardzie JWT i dlatego wyglądają dziwnie. sub to subject - identyfikator tego, kogo dotyczy przepustka, czyli po prostu id użytkownika. iat to issued at, moment wystawienia. exp to expiration, moment wygaśnięcia - to jego pilnuje weryfikacja czasu. Pola iat i exp biblioteka dopisuje sama; username, email i role to już Twoje własne claims.

Wystawienie przepustki przy logowaniu

Gdy hasło się zgadza, serwis podpisuje token i oddaje go klientowi:

async login(user: User) {
  const payload = {
    sub: user.id,
    username: user.username,
    role: user.role,
  };

  return {
    access_token: this.jwtService.sign(payload),
  };
}

jwtService.sign() bierze Twój obiekt, dokłada iat i exp zgodnie z signOptions, a całość pieczętuje tajnym kluczem. Zwrócony ciąg znaków to gotowa przepustka. Zauważ, czego tu nie ma: serwer niczego nie zapamiętuje. Nie powstaje żaden wpis w bazie sesji - cała wiedza o legioniście podróżuje w samym tokenie. Na tym polega różnica między przepustką a listą gości przy bramie.

Cały obieg wygląda więc tak: klient wysyła login i hasło, serwer weryfikuje je w bazie, serwer generuje token, klient dołącza go do każdego kolejnego żądania w nagłówku Authorization, a serwer odczytuje token i autoryzuje żądanie - bez sięgania do bazy po hasło.

Wartownik od przepustek

Kto właściwie sprawdza pieczęć przy każdym żądaniu? Robi to strategia - klasa, w której opisujesz, skąd wziąć token i jak go zweryfikować. Pełny system strategii poznasz w kolejnej lekcji; na razie wystarczy ta jedna, od przepustek:

@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor(private configService: ConfigService) {
    super({
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      ignoreExpiration: false,
      secretOrKey: configService.get('JWT_SECRET'),
    });
  }

  async validate(payload: JwtPayload) {
    return { userId: payload.sub, username: payload.username, role: payload.role };
  }
}

Trzy opcje w super() opisują, jak wartownik czyta dokument. jwtFromRequest mówi, skąd wziąć token - ExtractJwt.fromAuthHeaderAsBearerToken() wyciąga go z nagłówka Authorization: Bearer <token>, czyli najpopularniejszego miejsca. secretOrKey to ten sam klucz, którym token podpisano; bez niego nie da się sprawdzić pieczęci.

ignoreExpiration: false bywa mylące przez tę podwójną przeczącą formę, więc przeczytajmy ją wprost: nie ignoruj wygaśnięcia, czyli sprawdzaj exp i odrzucaj przeterminowane tokeny. To jest ustawienie, którego chcesz. Ustawienie true oznaczałoby, że przepustka sprzed roku wciąż otwiera bramy.

Metoda validate() dostaje już zweryfikowany payload - pieczęć sprawdzono, data ważności też, zanim Twój kod się uruchomił. Zwrócony obiekt trafia do request.user i staje się dostępny w kontrolerze. Zauważ, że nie ma tu zapytania do bazy: wszystkie potrzebne dane przyszły w tokenie, i to jest właśnie oszczędność, dla której wprowadziliśmy przepustki.

Podsumowanie

Legionista nosi przepustkę i nie podaje hasła przy każdej bramie:

  • JWT składa się z trzech części w stałej kolejności: Header, Payload, Signature,
  • payload jest kodowany, nie szyfrowany - każdy go odczyta, więc nie wkładaj tam haseł,
  • podpis nie ukrywa danych, tylko dowodzi, że nikt ich nie podmienił,
  • JwtModule.registerAsync z useFactory pozwala pobrać secret z ConfigService; klucz mieszka w .env, nigdy w kodzie,
  • signOptions.expiresIn ustala czas życia tokenu, issuer - wystawcę,
  • standardowe claims: sub (id użytkownika), iat (wystawiono), exp (wygasa),
  • jwtService.sign(payload) wystawia przepustkę, a serwer niczego nie zapamiętuje,
  • w JwtStrategy: ExtractJwt.fromAuthHeaderAsBearerToken() czyta token z nagłówka Bearer, ignoreExpiration: false odrzuca przeterminowane, a validate() dostaje payload już po weryfikacji.

W następnej lekcji poznasz Passport.js od strony całego systemu strategii - zobaczysz, że wartownik od przepustek to tylko jeden z wielu. A na razie zapamiętaj: JWT to przepustka z pieczęcią - dane w niej każdy przeczyta, ale podrobić ich nie zdoła nikt bez tajnego klucza.

Kod do tej lekcji: src/auth/jwt-config.ts
// JWT Tokens - Rzymskie Przepustki
// Kazda przepustka sklada sie z 3 czesci: Header, Payload, Signature
import { Module } from '@nestjs/common';
import { JwtModule, JwtService } from '@nestjs/jwt';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { Injectable } from '@nestjs/common';

// ===========================================
// 1. Konfiguracja JWT Module
// ===========================================

@Module({
  imports: [
    JwtModule.registerAsync({
      imports: [ConfigModule],
      useFactory: async (configService: ConfigService) => ({
        // Sekret do podpisywania tokenow
        secret: configService.get<string>('JWT_SECRET') || 'spqr-secret-key',
        signOptions: {
          expiresIn: '24h',      // Token wazny 24 godziny
          issuer: 'imperium-romanum', // Wydawca tokenu
          algorithm: 'HS256',    // Algorytm podpisu
        },
      }),
      inject: [ConfigService],
    }),
  ],
  exports: [JwtModule],
})
export class JwtConfigModule {}

// ===========================================
// 2. Serwis obslugujacy tokeny
// ===========================================

@Injectable()
export class TokenService {
  constructor(private jwtService: JwtService) {}

  // Tworzenie tokenu dostepu
  createAccessToken(legionary: { id: string; username: string; rank: string }) {
    const payload = {
      sub: legionary.id,
      username: legionary.username,
      rank: legionary.rank,
      type: 'access',
    };
    return this.jwtService.sign(payload, { expiresIn: '1h' });
  }

  // Tworzenie tokenu odswiezania
  createRefreshToken(legionary: { id: string }) {
    const payload = {
      sub: legionary.id,
      type: 'refresh',
    };
    return this.jwtService.sign(payload, { expiresIn: '7d' });
  }

  // Weryfikacja tokenu
  verifyToken(token: string) {
    try {
      const decoded = this.jwtService.verify(token);
      console.log('Token zdekodowany:', decoded);
      return decoded;
    } catch (error) {
      console.log('Token niewazny lub wygasl!');
      throw error;
    }
  }

  // Dekodowanie bez weryfikacji (np. do odczytu payloadu)
  decodeToken(token: string) {
    return this.jwtService.decode(token);
  }
}

// ===========================================
// 3. Struktura tokenu JWT
// ===========================================

console.log('=== Struktura JWT ===');
console.log('Header:  { alg: "HS256", typ: "JWT" }');
console.log('Payload: { sub: "1", username: "Caesar", rank: "consul" }');
console.log('Signature: HMACSHA256(header + payload, secret)');
console.log('');
console.log('Token = base64(header).base64(payload).signature');
console.log('Access Token: krotki czas zycia (1h)');
console.log('Refresh Token: dlugi czas zycia (7d)');

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Z ilu części składa się token JWT?

  2. 2. Co zawiera sekcja Payload tokenu JWT?

To 2 z 5 pytań do tej lekcji. Pozostałe rozwiążesz w grze.

Zadania praktyczne w grze

  • Edytor kodu

    Uzupełnij konfigurację JwtModule, ustawiając secret z ConfigService, czas wygaśnięcia na '24h' i issuer na 'LegionaryFleet'

  • Układanie w poziomie

    Ułóż części tokenu JWT w kolejności od lewej do prawej (tak jak występują w stringu)

  • Edytor kodu

    Uzupełnij klasę JwtStrategy, która dziedziczy po PassportStrategy(Strategy) i implementuje metodę validate sprawdzającą czy użytkownik istnieje

  • Klikanie w kolejności

    Ułóż elementy deklaracji klasy JwtStrategy w poprawnej kolejności

  • Układanie w pionie

    Uporządkuj kroki procesu logowania z użyciem JWT

  • Układanie w poziomie

    Ułóż składnię definiowania zmiennej JWT_SECRET w pliku .env

  • Edytor kodu

    Stwórz interfejs JwtPayload w TypeScript zawierający pola: sub (number), username (string), email (string), role (string), iat (number) i exp (number)

  1. PytanieStruktura tokenu JWT
  2. PytanieZawartość Payload w JWT
  3. Zadanie z kodemKonfiguracja JwtModule w NestJS
  4. Ułóż w kolejnościCzęści tokenu JWT
  5. PytanieMetoda ExtractJwt
  6. Zadanie z kodemImplementacja JwtStrategy
  7. Kliknij w kolejnościSkładnia deklaracji JwtStrategy
  8. PytanieWłaściwość ignoreExpiration w JWT
  9. Ułóż w kolejnościProces logowania z JWT
  10. Ułóż w kolejnościZmienne środowiskowe dla JWT
  11. Zadanie z kodemJwtPayload interface
  12. PytanieOpcja signOptions w JWT

Przydatne artykuły