Tema 14 · Guards & RBAC

14. Protección de Rutas con JwtAuthGuard, Decoradores Personalizados (@Roles) y RolesGuard

Implementa Control de Acceso Basado en Roles (RBAC) combinando metadatos con SetMetadata, Reflector y Guards reutilizables.

Autenticación vs. Autorización (RBAC) con Guards

Saber quién es el usuario (Autenticación con JwtAuthGuard) es solo la mitad de la seguridad. El siguiente paso es determinar qué tiene permitido hacer (Autorización / RBAC con RolesGuard): por ejemplo, que un estudiante pueda ver un curso pero solo un admin o instructor pueda eliminar módulos.

Cómo Funcionan SetMetadata y Reflector

NestJS permite crear decoradores declarativos propios (como @Roles('admin', 'instructor')) usando SetMetadata. Luego, dentro del método canActivate(context: ExecutionContext) de tu Guard, utilizas la clase helper Reflector para leer qué roles exige ese endpoint y compararlos contra request.user.rol:

Pieza Arquitectónica Rol en el Control de Acceso
@Roles('admin') Adjunta metadatos estáticos al método del controlador indicando los roles requeridos.
Reflector.getAllAndOverride() Extrae en tiempo de ejecución los metadatos de roles definidos a nivel de método o de clase controladora.
RolesGuard.canActivate() Retorna true si el usuario cumple el rol requerido, o false (disparando automáticamente 403 Forbidden).

⚡ Decorador @Roles, RolesGuard con Reflector y Uso en Controlador

Implementación limpia de RBAC para proteger endpoints administrativos en NestJS:

src/auth/guards/roles.guard.ts
Solo lectura
import {
  Injectable,
  CanActivate,
  ExecutionContext,
  SetMetadata,
  Controller,
  Post,
  UseGuards,
} from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { AuthGuard } from '@nestjs/passport';

export type RolUsuario = 'student' | 'instructor' | 'admin';
export const ROLES_KEY = 'roles_requeridos';

// 1. Decorador personalizado @Roles('admin', 'instructor')
export const Roles = (...roles: RolUsuario[]) => SetMetadata(ROLES_KEY, roles);

// 2. Guard de Autenticación JWT
@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {}

// 3. Guard de Autorización por Roles (RBAC)
@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private readonly reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const rolesRequeridos = this.reflector.getAllAndOverride<RolUsuario[]>(ROLES_KEY, [
      context.getHandler(),
      context.getClass(),
    ]);

    if (!rolesRequeridos || rolesRequeridos.length === 0) {
      return true; // Si la ruta no exige roles específicos, permite el paso
    }

    const request = context.switchToHttp().getRequest();
    const user = request.user as { userId: number; rol: RolUsuario } | undefined;

    return Boolean(user && rolesRequeridos.includes(user.rol));
  }
}

// 4. Uso declarativo en un controlador protegido:
@Controller('admin/cursos')
@UseGuards(JwtAuthGuard, RolesGuard)
export class AdminCursosController {
  @Post('publicar')
  @Roles('admin', 'instructor')
  publicarCurso() {
    return { mensaje: 'Curso publicado exitosamente en Kilopolis Academia.' };
  }
}
🧠
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección
1 Pregunta
Pregunta 1
¿Qué código de estado HTTP responde NestJS automáticamente cuando el método canActivate() de un Guard retorna false?
🦉
¿Tienes dudas con este tema?
Sócrates AI puede darte analogías y explicarte este código paso a paso.

🚀 ¿Quieres dominar NestJS Framework Profesional y crear proyectos reales?

Aprende arquitectura limpia, desarrollo web moderno, buenas prácticas y despliegue en producción con nuestro Bootcamp Fullstack Developer con mentorías en vivo.

🏛️ Autoría y Propiedad Intelectual: Obra educativa original de Juan Sebastián Amador para Kilopolis Academia, estructurada sobre las especificaciones y estándares abiertos del W3C, el estándar vivo de WHATWG y la documentación oficial de código abierto. © Todos los derechos reservados.