Guards bestimmen, ob eine Anfrage zum Route-Handler durchgelassen wird — sie sind NestJS's dedizierter Mechanismus für Autorisierung (und oft auch Authentifizierungsprüfungen). Ein Guard gibt true zurück, um die Anfrage zu erlauben, oder false/wirft eine Ausnahme, um sie zu blockieren.
@Injectable()
export class AuthGuard implements CanActivate {
canActivate(context: ExecutionContext): boolean {
const request = context.switchToHttp().getRequest();
return !!request.headers.authorization; // true = allow, false = block (403)
}
}
Ein Guard implementiert canActivate(), die einen boolean (oder Promise/Observable davon) zurückgibt. false zurückzugeben blockiert die Anfrage mit einem 403; du kannst auch eine spezifische Ausnahme werfen (z.B. 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 können auf Methoden-, Controller- oder globaler Ebene angewendet werden.
@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
}
}
Die Kombination eines @Roles()-Dekorators (Metadaten) mit einem Guard, der diesen ausliest (via Reflector), ist das Standardmuster für rollenbasierte Zugriffskontrolle.
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 sind der dedizierte, idiomatische NestJS-Mechanismus für Autorisierung — Kontrolle, welche Anfragen die Handler erreichen dürfen, basierend auf Authentifizierung und Berechtigungen.
Sie zu verstehen ist essentiell, weil praktisch jede echte Anwendung Routen schützen muss (Login erforderlich, Rollen/Berechtigungen prüfen), und Guards sind das richtige Werkzeug dafür (viel sauberer, als Authentifizierungslogik in Middleware oder jeden Handler zu pressen).
Die Standardmuster — ein JWT/Auth-Guard, der Anmeldedaten verifiziert und den Benutzer zur Anfrage hinzufügt, und rollenbasierte Guards, die einen @Roles()-Dekorator mit einem Reflector-lesenden Guard für RBAC kombinieren — sind fundamental zum Sichern von NestJS APIs.
Der Zugriff von Guards auf den reichhaltigen ExecutionContext (Kenntnis des Ziel-Handlers, der Klasse und der Anfrage) ist genau das, was sie für Autorisierungsentscheidungen geeignet macht, die Middleware nicht sauber treffen kann.
Zu wissen, wie man Guards schreibt, anwendet (Methode/Controller/global) und mit Metadaten-Dekoratoren kombiniert, ist Kernwissen zum Erstellen sicherer NestJS-Anwendungen und ein häufig vorkommendes, architektonisch wichtiges Thema im Framework.