Kurs NestJS · Moduł 4: Uwierzytelnianie

Refresh Tokens - odnawianie przepustek legionu

8 min czytania ·
W tej lekcji9

Access token z poprzednich lekcji żyje 15 minut. Legionista, którego co kwadrans wyrzuca z systemu, szybko zacznie przeklinać Architekta Vitruviusa. Wydłużenie przepustki do tygodnia to z kolei zaproszenie dla złodzieja: JWT jest ważny aż do daty wygaśnięcia, więc skradziony token otwiera fort przez siedem dni i nie da się go łatwo odwołać. Wyjściem są dwa tokeny o różnych zadaniach.

Czym są Refresh Tokens?

Wyobraź sobie system przepustek w obozie legionowym. Legionariusz dostaje dwa dokumenty:

  • Access Token (krótka przepustka wartownicza) - pozwala na wejście do obozu i wygasa po kilkunastu minutach
  • Refresh Token (pieczęć centuriona) - żyje kilka dni i pozwala wyrobić nową przepustkę bez ponownego stawania przed trybunałem

Dlaczego potrzebujemy dwóch tokenów?

  • Bezpieczeństwo - jeśli ktoś przechwyci access token, ma dostęp tylko na krótki czas
  • Wygoda - użytkownik nie musi logować się co kwadrans
  • Kontrola - możemy unieważnić refresh token, blokując odnowienie dostępu

Mechanizm refresh tokenów to fundament bezpiecznych systemów uwierzytelniania w produkcyjnych aplikacjach.

Generowanie pary tokenów

Oba tokeny podpisujemy osobnymi sekretami, JWT_ACCESS_SECRET i JWT_REFRESH_SECRET, więc jednego nie da się podrobić ani użyć zamiast drugiego. Tak wygląda logowanie:

// auth/auth.service.ts
import { Injectable, UnauthorizedException } from '@nestjs/common';
import { JwtService } from '@nestjs/jwt';
import { ConfigService } from '@nestjs/config';
import { createHash } from 'node:crypto';

@Injectable()
export class AuthService {
  constructor(
    private jwtService: JwtService,
    private configService: ConfigService,
    private usersService: UsersService,
  ) {}

  async login(loginDto: LoginDto): Promise<TokenPair> {
    const user = await this.usersService.validateCredentials(
      loginDto.username,
      loginDto.password,
    );

    if (!user) {
      throw new UnauthorizedException('Nieprawidłowe dane logowania, legionariuszu!');
    }

    // Generuj parę tokenów
    const tokens = await this.generateTokenPair(user);

    // Zapisz w bazie skrót SHA-256 refresh tokenu, nie sam token
    const hashedRefreshToken = this.hashToken(tokens.refreshToken);
    await this.usersService.updateRefreshToken(user.id, hashedRefreshToken);

    return tokens;
  }

validateCredentials() sprawdza hasło przez bcrypt.compare() z lekcji o hashowaniu. W bazie ląduje wyłącznie skrót refresh tokenu - access tokenu nie zapisujemy nigdzie, bo po kwadransie i tak wygaśnie. Typ UserDocument poznasz za chwilę przy schemacie.

Parę tokenów tworzy osobna metoda:

  async generateTokenPair(user: UserDocument): Promise<TokenPair> {
    const payload = {
      sub: user.id,
      username: user.username,
      role: user.role,
      cohort: user.cohortName,
    };

    const [accessToken, refreshToken] = await Promise.all([
      this.jwtService.signAsync(payload, {
        secret: this.configService.get('JWT_ACCESS_SECRET'),
        expiresIn: '15m', // Krótka przepustka wartownicza - 15 minut
      }),
      this.jwtService.signAsync(payload, {
        secret: this.configService.get('JWT_REFRESH_SECRET'),
        expiresIn: '7d', // Pieczęć centuriona - dłuższy czas życia
      }),
    ]);

    return { accessToken, refreshToken };
  }

  // Skrót refresh tokenu: SHA-256, bo bcrypt czyta tylko 72 bajty
  private hashToken(token: string): string {
    return createHash('sha256').update(token).digest('hex');
  }
}

signAsync() przyjmuje sekret i expiresIn dla każdego tokenu osobno, a Promise.all() podpisuje oba równolegle. Payload jest ten sam, różnią się tylko sekret i czas życia. Zwróć uwagę na hashToken(): celowo używa SHA-256, a nie bcrypt. bcrypt czyta tylko 72 bajty, a dwa tokeny JWT tego samego legionisty mają identyczny początek (nagłówek i pierwsze pola payloadu), więc bcrypt.compare(staryToken, hashNowego) zwróciłoby true. Token jest długi i losowy, więc szybki skrót w zupełności wystarcza.

Jedna rzecz poza tym plikiem: JwtStrategy musi weryfikować access tokeny tym samym sekretem, którym je podpisujesz. Jeśli wprowadzasz JWT_ACCESS_SECRET, zmień też jej secretOrKey.

Endpoint odnawiania tokenu

Kontroler wystawia trzy trasy: logowanie, odświeżenie i wylogowanie:

// auth/auth.controller.ts
@Controller('auth')
export class AuthController {
  constructor(private authService: AuthService) {}

  @Post('login')
  async login(@Body() loginDto: LoginDto) {
    return this.authService.login(loginDto);
  }

  @Post('refresh')
  async refreshTokens(@Body('refreshToken') refreshToken: string) {
    return this.authService.refreshTokens(refreshToken);
  }

  @Post('logout')
  @UseGuards(JwtAuthGuard)
  async logout(@Req() req) {
    // Unieważnij refresh token przy wylogowaniu
    await this.authService.logout(req.user.userId);
    return { message: 'Legionariusz wylogowany pomyślnie' };
  }
}

/auth/refresh nie ma JwtAuthGuard, bo wywołujemy go właśnie wtedy, gdy access token wygasł - poświadczeniem jest tu sam refresh token. Wylogowanie jest chronione, a req.user.userId pochodzi z JwtStrategy, której validate() zwraca { userId, username, role }.

Logika odnawiania w serwisie

Metoda refreshTokens() zaczyna od sprawdzenia, czy pieczęć jest prawdziwa i czyj to dokument:

// auth/auth.service.ts (kontynuacja)
async refreshTokens(refreshToken: string): Promise<TokenPair> {
  // 1. Zweryfikuj refresh token
  let payload;
  try {
    payload = await this.jwtService.verifyAsync(refreshToken, {
      secret: this.configService.get('JWT_REFRESH_SECRET'),
    });
  } catch (error) {
    throw new UnauthorizedException('Pieczęć centuriona wygasła - zaloguj się ponownie!');
  }

  // 2. Znajdź użytkownika i sprawdź zapisany refresh token
  const user = await this.usersService.findById(payload.sub);

  if (!user || !user.hashedRefreshToken) {
    throw new UnauthorizedException('Dostęp odrzucony!');
  }

verifyAsync() z sekretem refresh sprawdza podpis i datę wygaśnięcia. Brak zapisanego skrótu oznacza, że legionista się wylogował albo jego sesję unieważniono.

Dalej porównujemy token z bazą i wydajemy nową parę:

  // 3. Porównaj skrót tokenu z zapisanym w bazie
  const isTokenValid = this.hashToken(refreshToken) === user.hashedRefreshToken;

  if (!isTokenValid) {
    // Potencjalna kradzież tokenu - unieważnij wszystkie sesje
    await this.usersService.updateRefreshToken(user.id, null);
    throw new UnauthorizedException('Token unieważniony - wykryto podejrzaną aktywność!');
  }

  // 4. Wygeneruj nową parę tokenów (Token Rotation)
  const newTokens = await this.generateTokenPair(user);

  // 5. Zapisz nowy refresh token
  const hashedNewRefreshToken = this.hashToken(newTokens.refreshToken);
  await this.usersService.updateRefreshToken(user.id, hashedNewRefreshToken);

  return newTokens;
}

async logout(userId: string): Promise<void> {
  // Unieważnij refresh token
  await this.usersService.updateRefreshToken(userId, null);
}

Jeśli skrót się nie zgadza, ktoś przyniósł poprawnie podpisany, ale nieaktualny token - to sygnał kradzieży, więc kasujemy zapisany skrót i wszyscy muszą zalogować się ponownie. logout() robi to samo na życzenie użytkownika.

Token Rotation - rotacja tokenów

Kluczowa technika bezpieczeństwa: przy każdym odświeżeniu generujemy nowy refresh token i unieważniamy stary. Jeśli ktoś ukradnie refresh token i spróbuje go użyć po rotacji - wykryjemy to:

// Schemat ochrony przed kradzieżą tokenów
// 1. Legionariusz loguje się → otrzymuje AT1 + RT1
// 2. AT1 wygasa → wysyła RT1 → otrzymuje AT2 + RT2 (RT1 unieważniony)
// 3. Złodziej próbuje użyć RT1 → ODMOWA (token już obrócony)
// 4. System wykrywa użycie starego tokenu → unieważnia WSZYSTKIE sesje użytkownika

Stary RT1 wciąż ma poprawny podpis i datę ważności. Odrzuca go dopiero porównanie ze skrótem w bazie - i dlatego ten skrót przechowujemy.

Schemat użytkownika z refresh tokenem

Skrót trafia do pola hashedRefreshToken w schemacie Mongoose:

// users/user.schema.ts (Mongoose)
import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';
import { HydratedDocument } from 'mongoose';

@Schema({ timestamps: true })
export class User {
  @Prop({ required: true, unique: true })
  username: string;

  @Prop({ required: true })
  password: string;

  @Prop()
  email: string;

  @Prop({ default: 'miles' })
  role: string;

  @Prop({ type: String, default: null })
  hashedRefreshToken: string | null;

  @Prop()
  cohortName: string;
}

export type UserDocument = HydratedDocument<User>;
export const UserSchema = SchemaFactory.createForClass(User);

Opcja nullable pochodzi z TypeORM, a Mongoose po prostu ją ignoruje. Tutaj null jest dozwolone domyślnie, a przy typie string | null trzeba jawnie podać type: String. HydratedDocument<User> to wzorzec z aktualnej dokumentacji NestJS: klasa opisuje pola, a typ dokumentu dodaje id i metody Mongoose.

Refresh Token Guard

Zamiast weryfikować token ręcznie, możesz oddać to Passportowi. Strategia o nazwie 'jwt-refresh' czyta token z pola body:

// auth/guards/refresh-token.guard.ts
import { Injectable } from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';

@Injectable()
export class RefreshTokenGuard extends AuthGuard('jwt-refresh') {}

// auth/strategies/refresh-token.strategy.ts
import { Injectable } from '@nestjs/common';
import { PassportStrategy } from '@nestjs/passport';
import { ExtractJwt, Strategy } from 'passport-jwt';
import { ConfigService } from '@nestjs/config';
import { Request } from 'express';

@Injectable()
export class RefreshTokenStrategy extends PassportStrategy(Strategy, 'jwt-refresh') {
  constructor(private configService: ConfigService) {
    super({
      jwtFromRequest: ExtractJwt.fromBodyField('refreshToken'),
      secretOrKey: configService.getOrThrow('JWT_REFRESH_SECRET'),
      passReqToCallback: true,
    });
  }

  validate(req: Request, payload: any) {
    const refreshToken = req.body.refreshToken;
    return { ...payload, refreshToken };
  }
}

passReqToCallback: true przekazuje do validate() cały request, więc surowy token trafia do req.user.refreshToken. Strategia sprawdza tylko podpis i datę, dlatego porównanie ze skrótem w bazie i tak zostaje w serwisie. Po stronie klienta refresh token najlepiej trzymać w ciasteczku httpOnly, niedostępnym dla JavaScriptu - to polecam.

Praktyczne ćwiczenie

Zaimplementuj kompletny system refresh tokenów dla legionu, krok po kroku:

// Twój kod tutaj
// 1. Skonfiguruj dwa sekrety JWT (access i refresh) w ConfigService
// 2. Zaimplementuj endpoint POST /auth/refresh z walidacją
// 3. Dodaj Token Rotation przy każdym odświeżeniu
// 4. Zaimplementuj wykrywanie ponownego użycia starego tokenu
// 5. Dodaj czyszczenie wygasłych tokenów (cron job)

Do czyszczenia starych wpisów przyda się @nestjs/schedule z dekoratorem @Cron().

Podsumowanie

Zostałeś mianowany strażnikiem bram Imperium! Teraz umiesz:

  • Generować pary tokenów - access token (krótki) + refresh token (długi)
  • Implementować Token Rotation - nowy refresh token przy każdym odświeżeniu
  • Wykrywać kradzież tokenów - unieważnianie sesji przy ponownym użyciu starego tokenu
  • Bezpiecznie przechowywać refresh tokeny w bazie jako skrót SHA-256
  • Implementować logout - unieważnianie refresh tokenu przy wylogowaniu
  • Tworzyć Passport Strategies dla refresh tokenów

W następnej lekcji zajmiemy się OAuth i logowaniem przez Google.

Pamiętaj: przepustka wartownicza ma być krótka, a pieczęć centuriona - jednorazowa, bo każda rotacja zamyka drogę temu, kto ukradł poprzednią.

Kod do tej lekcji: src/auth/refresh-tokens.ts
// Refresh Tokens - Odnawianie przepustek legionu
import { Injectable, UnauthorizedException } from '@nestjs/common';
import { JwtService } from '@nestjs/jwt';
import { ConfigService } from '@nestjs/config';

interface TokenPair {
  accessToken: string;
  refreshToken: string;
}

interface JwtPayload {
  sub: string;
  username: string;
  role: string;
}

@Injectable()
export class RefreshTokenService {
  constructor(
    private jwtService: JwtService,
    private configService: ConfigService,
  ) {}

  // TODO: Zaimplementuj generowanie pary tokenow
  // accessToken - krotki czas zycia (15m)
  // refreshToken - dlugi czas zycia (7d)
  async generateTokenPair(payload: JwtPayload): Promise<TokenPair> {
    // TODO: Wygeneruj accessToken
    const accessToken = this.jwtService.sign(payload, {
      secret: '', // TODO: pobierz JWT_ACCESS_SECRET z configService
      expiresIn: '', // TODO: ustaw na '15m'
    });

    // TODO: Wygeneruj refreshToken z innym sekretem
    const refreshToken = this.jwtService.sign(payload, {
      secret: '', // TODO: pobierz JWT_REFRESH_SECRET z configService
      expiresIn: '', // TODO: ustaw na '7d'
    });

    return { accessToken, refreshToken };
  }

  // TODO: Zaimplementuj odswiezanie tokenow
  async refreshTokens(oldRefreshToken: string): Promise<TokenPair> {
    try {
      // TODO: Zweryfikuj stary refreshToken
      const payload = this.jwtService.verify(oldRefreshToken, {
        secret: '', // TODO: ten sam sekret co przy generowaniu refresh
      });

      // TODO: Wygeneruj nowa pare tokenow
      const newPayload: JwtPayload = {
        sub: payload.sub,
        username: payload.username,
        role: payload.role,
      };

      return this.generateTokenPair(newPayload);
    } catch (error) {
      throw new UnauthorizedException('Refresh token wygasl lub jest nieprawidlowy!');
    }
  }
}

console.log('Access Token: krotki czas zycia (15 minut)');
console.log('Refresh Token: dlugi czas zycia (7 dni)');
console.log('Rotacja tokenow zwieksza bezpieczenstwo');

Hasła z dokumentacji w tej lekcji

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. Jaka jest typowa różnica w czasie życia między Access Token a Refresh Token?

Zadania praktyczne w grze

  • Układanie w pionie

    Uszereguj kroki odświeżania tokenu JWT:

  1. PytanieCzas życia Access Token vs Refresh Token
  2. Ułóż w kolejnościProces odświeżania tokenu

Przydatne artykuły