A guardok meghatározzák, hogy egy kérés jogosult-e folytatódni a route handler-ig — ezek a NestJS dedikált mechanizmusa az engedélyezéshez (és gyakran a hitelesítés ellenőrzéséhez). Egy guard true értéket ad vissza a kérés engedélyezéséhez, vagy false/exception-t dob annak blokkolásához.
@Injectable()
export class AuthGuard implements CanActivate {
canActivate(context: ExecutionContext): boolean {
const request = context.switchToHttp().getRequest();
return !!request.headers.authorization; // true = allow, false = block (403)
}
}
Egy guard a canActivate() metódust valósítja meg, amely boolean értéket (vagy annak Promise/Observable-jét) ad vissza. A false visszaadása 403-mal blokkolja a kérést; konkrét exception-t is dobhat (pl. UnauthorizedException).
@UseGuards(AuthGuard) // on a single route
@Get("profile")
getProfile() {}
@UseGuards(AuthGuard) // on a whole controller (all routes)
@Controller("admin")
export class AdminController {}
app.useGlobalGuards(new AuthGuard()); // globally (all routes)
A guardok metódus, kontroller vagy globális szinten alkalmazhatók.
@Injectable()
export class JwtAuthGuard implements CanActivate {
constructor(private jwtService: JwtService) {}
async canActivate(context: ExecutionContext): Promise<boolean> {
const request = context.switchToHttp().getRequest();
const token = request.headers.authorization?.split(" ")[1];
if (!token) throw new UnauthorizedException();
try {
request.user = await this.jwtService.verifyAsync(token); // attach the user
return true;
} catch {
throw new UnauthorizedException("Invalid token");
}
}
}
// a @Roles decorator stores required roles as metadata
@Roles("admin")
@Get("users")
listUsers() {}
// the RolesGuard reads the metadata and checks the user's roles
@Injectable()
export class RolesGuard implements CanActivate {
constructor(private reflector: Reflector) {}
canActivate(ctx: ExecutionContext): boolean {
const roles = this.reflector.get<string[]>("roles", ctx.getHandler());
const { user } = ctx.switchToHttp().getRequest();
return roles.some(role => user.roles?.includes(role)); // allow if the user has a required role
}
}
Egy @Roles() dekorátor (metaadatok) kombinálása egy olyan guard-dal, amely azt olvassa (a Reflector segítségével), a szerep alapú hozzáférés-vezérlés standard mintája.
The ExecutionContext gives guards rich info (the handler, class, request) — more
than plain middleware — which is why guards (not middleware) are the right place
for authorization decisions.
A guardok a NestJS dedikált, idiomatikus mechanizmusa az engedélyezéshez — annak szabályozásához, mely kérések jogosultak a handler-ekig eljutni a hitelesítés és az engedélyek alapján.
A megértésük lényeges, mert szinte minden valódi alkalmazásnak védelemmel kell ellátnia az útvonalakat (bejelentkezés szükséges, szerepek/engedélyek ellenőrzése), és a guardok az helyes eszköz ehhez (sokkal tisztább, mint az auth logika middleware-be vagy az egyes handler-ekbe pakolása).
A standard minták — egy JWT/auth guard, amely ellenőrzi a hitelesítő adatokat és csatolja a felhasználót a kéréshez, valamint a szerep alapú guardok, amelyek a @Roles() dekorátor kombinálják egy Reflector-olvasó guard-dal az RBAC-hoz — alapvetőek a NestJS API-k biztonságossá tételéhez.
A guardok gazdag ExecutionContext-hez való hozzáférése (a cél handler, osztály és kérés ismerete) pontosan az, ami megfelelővé teszi őket az engedélyezési döntésekhez, amelyeket a middleware nem tud tisztán meghozni.
Annak tudása, hogyan kell guardian-okat írni, alkalmazni (metódus/kontroller/globális), és metaadatok dekorátorokkal kombinálni, alapvető tudás a biztonságos NestJS alkalmazások építéséhez, és gyakori, architekturálisan fontos téma a keretrendszerben.