fullstack.org.ua

Roles Guards · fullstack.org.ua

Середній14 хв· Fullstack Team

Roles Guards

Реалізуєте декоратор ролей і guard, який перевіряє роль користувача перед доступом до маршруту.

Що таке ролі та guards

Роль визначає набір дозволів користувача. Наприклад:

user може переглядати власний профіль;
manager може переглядати звіти;
admin має доступ до адміністративних маршрутів.

Guard у NestJS перевіряє, чи може запит продовжити виконання. Метод canActivate() повертає:

true — доступ дозволено;
false — доступ заборонено;
або guard може викинути виняток, наприклад ForbiddenException.

Перевірка ролі — це частина авторизації. Вона виконується після автентифікації, коли застосунок уже знає, хто саме робить запит.

Очікується, що guard автентифікації додав користувача до request.user:

typescript

request.user = {
  id: '42',
  role: Role.Admin,
};

typescript

import { SetMetadata } from '@nestjs/common';
import { Role } from './role.enum';

export const ROLES_KEY = 'roles';

export const Roles = (...roles: Role[]) => {
  return SetMetadata(ROLES_KEY, roles);
};

typescript

import {
  CanActivate,
  ExecutionContext,
  ForbiddenException,
  Injectable,
} from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { Request } from 'express';

import { Role } from './role.enum';
import { ROLES_KEY } from './roles.decorator';

interface AuthenticatedRequest extends Request {
  user?: {
    role?: Role;
  };
}

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private readonly reflector: Reflector) {}

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

    if (!requiredRoles) {
      return true;
    }

    const request = context
      .switchToHttp()
      .getRequest<AuthenticatedRequest>();

    const userRole = request.user?.role;

    if (!userRole || !requiredRoles.includes(userRole)) {
      throw new ForbiddenException(
        'У вас немає необхідної ролі для цього маршруту',
      );
    }

    return true;
  }
}

typescript

import {
  Controller,
  Get,
  UseGuards,
} from '@nestjs/common';

import { Role } from './role.enum';
import { Roles } from './roles.decorator';
import { RolesGuard } from './roles.guard';
import { AuthenticationGuard } from './authentication.guard';

@Controller('admin')
@UseGuards(AuthenticationGuard, RolesGuard)
export class AdminController {
  @Get('users')
  @Roles(Role.Admin)
  getUsers() {
    return {
      message: 'Список користувачів доступний адміністратору',
    };
  }

  @Get('reports')
  @Roles(Role.Admin, Role.Manager)
  getReports() {
    return {
      message: 'Звіти доступні адміністратору або менеджеру',
    };
  }
}

typescript

import { SetMetadata } from '@nestjs/common';

import { Role } from './role.enum';

export const ROLES_KEY = 'roles';

export const Roles = (...roles: Role[]) => {
  return SetMetadata(ROLES_KEY, roles);
};

typescript

import {
  CanActivate,
  ExecutionContext,
  ForbiddenException,
  Injectable,
} from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { Request } from 'express';

import { Role } from './role.enum';
import { ROLES_KEY } from './roles.decorator';

interface AuthenticatedRequest extends Request {
  user?: {
    role?: Role;
  };
}

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private readonly reflector: Reflector) {}

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

    if (!requiredRoles) {
      return true;
    }

    const request = context
      .switchToHttp()
      .getRequest<AuthenticatedRequest>();

    const userRole = request.user?.role;

    if (!userRole || !requiredRoles.includes(userRole)) {
      throw new ForbiddenException(
        'У вас немає необхідної ролі для цього маршруту',
      );
    }

    return true;
  }
}

typescript

import {
  CanActivate,
  ExecutionContext,
  Injectable,
  UnauthorizedException,
} from '@nestjs/common';
import { Request } from 'express';

import { Role } from './role.enum';

interface AuthenticatedRequest extends Request {
  user?: {
    role: Role;
  };
}

@Injectable()
export class AuthenticationGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const request = context
      .switchToHttp()
      .getRequest<AuthenticatedRequest>();

    const roleHeader = request.headers['x-role'];

    if (typeof roleHeader !== 'string') {
      throw new UnauthorizedException(
        'Передайте роль у заголовку x-role',
      );
    }

    const isValidRole = Object.values(Role).includes(roleHeader as Role);

    if (!isValidRole) {
      throw new UnauthorizedException('Невідома роль користувача');
    }

    request.user = {
      role: roleHeader as Role,
    };

    return true;
  }
}

typescript

import {
  Controller,
  Get,
  UseGuards,
} from '@nestjs/common';

import { AuthenticationGuard } from './authentication.guard';
import { Role } from './role.enum';
import { Roles } from './roles.decorator';
import { RolesGuard } from './roles.guard';

@Controller('admin')
@UseGuards(AuthenticationGuard, RolesGuard)
export class AdminController {
  @Get('users')
  @Roles(Role.Admin)
  getUsers() {
    return {
      message: 'Цей маршрут доступний лише адміністратору',
    };
  }

  @Get('reports')
  @Roles(Role.Admin, Role.Manager)
  getReports() {
    return {
      message: 'Цей маршрут доступний адміністратору або менеджеру',
    };
  }

  @Get('profile')
  getProfile() {
    return {
      message: 'Цей маршрут не має обмеження за роллю',
    };
  }
}

typescript

import { Module } from '@nestjs/common';

import { AdminController } from './admin.controller';
import { AuthenticationGuard } from './authentication.guard';
import { RolesGuard } from './roles.guard';

@Module({
  controllers: [AdminController],
  providers: [AuthenticationGuard, RolesGuard],
})
export class AppModule {}

typescript

@Controller('settings')
@Roles(Role.Admin)
@UseGuards(AuthenticationGuard, RolesGuard)
export class SettingsController {
  @Get()
  getSettings() {
    return {
      message: 'Налаштування доступні адміністратору',
    };
  }

  @Get('public')
  getPublicSettings() {
    return {
      message: 'Публічні налаштування',
    };
  }
}

typescript

@Controller('reports')
@Roles(Role.Manager, Role.Admin)
@UseGuards(AuthenticationGuard, RolesGuard)
export class ReportsController {
  @Get()
  getReports() {
    return {
      message: 'Доступ для менеджера або адміністратора',
    };
  }

  @Get('admin-only')
  @Roles(Role.Admin)
  getAdminReport() {
    return {
      message: 'Доступ лише для адміністратора',
    };
  }
}