Guards menentukan apakah request diizinkan melanjutkan ke route handler — mereka adalah mekanisme dedikasi NestJS untuk otorisasi (dan sering pemeriksaan autentikasi). Guard mengembalikan true untuk mengizinkan request atau false/throw untuk membloknya.
@Injectable()
export class AuthGuard implements CanActivate {
canActivate(context: ExecutionContext): boolean {
const request = context.switchToHttp().getRequest();
return !!request.headers.authorization; // true = allow, false = block (403)
}
}
Guard mengimplementasikan canActivate(), yang mengembalikan boolean (atau Promise/Observable darinya). Mengembalikan false memblokir request dengan 403; Anda juga dapat melempar exception tertentu (misalnya 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)
Guards dapat diterapkan di tingkat metode, kontroler, atau global.
@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
}
}
Menggabungkan dekorator @Roles() (metadata) dengan guard yang membacanya (melalui Reflector) adalah pola standar untuk kontrol akses berbasis peran.
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.
Guards adalah mekanisme dedikasi dan idiomatik NestJS untuk otorisasi — mengontrol request mana yang diizinkan mencapai handler berdasarkan autentikasi dan izin.
Memahaminya sangat penting karena hampir setiap aplikasi nyata perlu melindungi rute (memerlukan login, memeriksa peran/izin), dan guards adalah alat yang tepat untuk ini (jauh lebih bersih daripada menyumbat logika auth ke middleware atau setiap handler).
Pola standar — guard JWT/auth yang memverifikasi kredensial dan melampirkan pengguna ke request, dan guards berbasis peran menggabungkan dekorator @Roles() dengan guard pembaca Reflector untuk RBAC — adalah fundamental untuk mengamankan API NestJS.
Akses guards ke ExecutionContext yang kaya (mengetahui handler target, kelas, dan request) adalah alasan tepat mengapa mereka cocok untuk keputusan otorisasi yang tidak dapat dilakukan middleware dengan bersih.
Mengetahui cara menulis, menerapkan (metode/kontroler/global), dan menggabungkan guards dengan dekorator metadata adalah pengetahuan inti untuk membangun aplikasi NestJS yang aman dan topik yang sering serta penting secara arsitektural dalam framework.