NestJS CanActivate와 커스텀 Roles 데코레이터로 권한 인가 가드 구현하기

TL;DR#

• NestJS의 CanActivate를 구현하면 엔드포인트 진입 전에 인가(authorization)를 검사하는 가드를 만들 수 있습니다.
• @Roles('admin')처럼 역할을 명시하는 데코레이터는 NestJS 기본 제공이 아니므로 SetMetadata로 직접 만들어야 합니다.
• 가드 안에서 Reflector로 해당 메타데이터를 읽어, 요청한 사용자의 역할과 비교해 true/false를 반환하면 역할 기반 인가가 완성됩니다.
• 이 글에서는 Prisma로 사용자 테이블의 user_type을 조회해 데코레이터 인자와 비교하는 방식으로 구현했습니다.

무엇을 만들려고 하는가#

관리자만 접근할 수 있어야 하는 엔드포인트가 있다고 가정하겠습니다. 일반 사용자가 해당 API를 호출하면 예외로 막고 싶습니다. 목표는 아래처럼 @Roles('admin')만 붙이면 가드가 동작하도록 만드는 것입니다.

복사
// * Roles 데코레이션을 사용함으로써 해당 엔드포인트의 auth guard를 유연하게 가능합니다.
@Post()
@Roles('admin')
async create(@Body() createCatDto: CreateCatDto) {
  this.catsService.create(createCatDto);
}

문제는 Roles가 NestJS에서 기본으로 제공하는 데코레이터가 아니라는 점입니다. 따라서 데코레이터와 이를 해석하는 가드를 직접 만들어야 합니다.

AuthGuard 구성하기#

먼저 CanActivate를 구현하는 가드의 뼈대를 만듭니다.

복사
//src/guards/auth.guard.ts
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Observable } from 'rxjs';

@Injectable()
export class AuthGuard implements CanActivate {
  canActivate(
    context: ExecutionContext,
  ): boolean | Promise<boolean> | Observable<boolean> {
	   return true
  }
}

이 가드에서 요청을 받아 헤더의 authorization 정보를 꺼내고, Roles 데코레이터에 넘긴 인자와 일치하는지 비교합니다. 일치하면 true, 일치하지 않으면 false를 반환하는 로직을 채워 넣을 것입니다.

컨트롤러에 가드 바인딩하기#

@nestjs/common이 제공하는 UseGuards 데코레이터로 위에서 만든 AuthGuard를 컨트롤러에 적용합니다.

복사
@Controller('cats')
@UseGuards(AuthGuard)
export class CatsController {}

App 모듈에서 전역 가드 설정하기#

특정 컨트롤러가 아니라 애플리케이션 전체에 가드를 적용하려면 APP_GUARD로 등록합니다.

복사
import { Module } from '@nestjs/common';
import { APP_GUARD } from '@nestjs/core';

@Module({
  providers: [
    {
      provide: APP_GUARD,
      useClass: AuthGuard,
    },
  ],
})
export class AppModule {}

Roles 데코레이터 만들기#

이제 핵심인 Roles 데코레이터를 직접 만듭니다.

복사
// src/decorators/roles.decoration.ts
import { SetMetadata } from '@nestjs/common';

export const Roles = (...roles: string[]) => SetMetadata('roles', roles);

SetMetadata로 라우트 핸들러에 roles라는 이름의 커스텀 메타데이터를 설정합니다. rest 파라미터를 사용했기 때문에 여러 개의 역할을 인자로 받을 수 있습니다.

여기서 설정한 roles 메타데이터를 가드 클래스에서 읽어와 분기 처리하고, true나 false를 반환하도록 만들 차례입니다.

가드에 인가 로직 구현하기#

가드 안에서 Reflector로 메타데이터를 읽어 실제 인가를 판단합니다.

복사
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Reflector } from '@nestjs/core';

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

  canActivate(context: ExecutionContext): boolean {
	const roles = this.reflector.getAllAndOverride('roles', [
      context.getHandler(),
      context.getClass(),
    ]);
    if (roles.length) {
      const request = context.switchToHttp().getRequest();
      const token = request.headers?.authorization?.split('Bearer ')[1];
      try {
        const payload = (await jwt.verify(
          token,
          process.env.JSON_TOKEN_KEY,
        )) as JWTPayload;
        const user = await this.prismaService.user.findUnique({
          where: {
            id: payload.id,
          },
        });
        if (!user) return false;
        if (roles.includes(user.user_type)) return true;
        return false;
      } catch (error) {
        return false;
      }
    }

    return true;
  }
}

Reflector를 사용하면 Roles 데코레이터에서 설정한 커스텀 메타데이터를 가져올 수 있습니다.

예를 들어 컨트롤러에서 @Roles('admin', 'admin2')를 사용했다면 roles에는 ['admin', 'admin2']가 들어옵니다. 즉 Roles 데코레이터에 인자가 들어와 데코레이터가 적용된 경우에만 첫 번째 조건문을 타게 되고, 그 안에서 프로젝트에 맞는 인가 로직을 구성하면 됩니다.

정리#

이 글에서는 Prisma ORM으로 DB에 접근해, 사용자 테이블의 user_type과 데코레이터 인자를 비교하는 방식으로 인가를 처리했습니다. 핵심 흐름은 다음과 같습니다.

• CanActivate로 가드를 만들고 UseGuards 또는 APP_GUARD로 바인딩한다.
• SetMetadata로 Roles 커스텀 데코레이터를 만든다.
• 가드에서 Reflector로 메타데이터를 읽어 사용자 역할과 비교한다.

인증·인가 정책은 프로젝트마다 다르므로, 토큰 검증과 사용자 조회 부분은 각자 환경에 맞게 바꿔 끼우면 됩니다.