Kurs NestJS · Moduł 4: Uwierzytelnianie
Refresh Tokens - odnawianie przepustek legionu
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żytkownikaStary 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. 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: