Guard menentukan apakah permintaan dibenarkan untuk meneruskan ke route handler — ini adalah mekanisme khusus NestJS untuk autorisasi (dan sering juga pemeriksaan autentikasi). Sebuah guard mengembalikan true untuk membenarkan permintaan atau false/melemparkan pengecualian 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)
}
}
Sebuah guard mengimplementasikan canActivate(), yang mengembalikan boolean (atau Promise/Observable darinya). Mengembalikan false memblokir permintaan dengan 403; Anda juga dapat melemparkan pengecualian 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)
Guard dapat diterapkan pada tingkat metode, pengontrol, 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.
Guard adalah mekanisme khusus dan idiomatik NestJS untuk autorisasi — mengontrol permintaan mana yang dibenarkan mencapai handler berdasarkan autentikasi dan izin.
Memahaminya sangat penting karena hampir setiap aplikasi nyata perlu melindungi rute (memerlukan login, memeriksa peran/izin), dan guard adalah alat yang benar untuk ini (jauh lebih bersih daripada meletakkan logika autentikasi di middleware atau setiap handler).
Pola standar — guard JWT/autentikasi yang memverifikasi kredensial dan melampirkan pengguna ke permintaan, dan guard berbasis peran yang menggabungkan dekorator @Roles() dengan guard pembaca Reflector untuk RBAC — adalah fundamental untuk mengamankan API NestJS.
Akses guard ke ExecutionContext yang kaya (mengetahui target handler, kelas, dan permintaan) adalah alasan mereka cocok untuk keputusan autorisasi yang middleware tidak dapat lakukan dengan bersih.
Mengetahui cara menulis, menerapkan (metode/pengontrol/global), dan menggabungkan guard dengan dekorator metadata adalah pengetahuan inti untuk membangun aplikasi NestJS yang aman dan topik penting arsitektur yang sering muncul dalam kerangka kerja.