NestJS Request Lifecycle (2) - Guard

이전 글

• 2022.12.22 - [Backend/NestJS] - NestJS Request Lifecycle (0) - 개요
• 2022.12.22 - [Backend/NestJS] - NestJS Request Lifecycle (1) - Middleware

---

가드

NestJS 내에서 가드란 요청 생명주기에서 미들웨어의 뒤쪽, 인터셉터의 앞쪽에 위치하여 특정 경로로의 요청을 승인할지 말지에 대한 판단을 내리는 역할을 한다. Express로 로직을 개발하다보면 사용자의 권한에 따른 처리를 미들웨어에서 하는 경우가 잦은데, NestJS에서는 이를 가드라는 생명주기에서 따로 처리를 해주는 것이다.

미들웨어 대신 가드를 사용하는 이유?

그렇다면 NestJS에서는 왜 굳이 가드를 따로 두는 것일까? NestJS 공식문서에서는 다음과 같이 언급하고 있다. (의역 다수...)

미들웨어는 본질적으로 똑똑하지 못합니다. 미들웨어는 next() 함수가 호출된 뒤 어떤 핸들러가 실행되는지 모르기 때문입니다. 반면, 가드는 ExecutionContext 객체에 접근할 수 있기 때문에 이후 어떤 핸들러가 실행되는지 정확히 알 수 있습니다. 가드는 Pipe, Interceptor, Exception filter와 비슷하게 디자인되어, 요청/반환 주기 내 적절한 지점에 더 선언적으로 포함시킬 수 있습니다. 결론적으로, 코드를 더 선언적이고 DRY 원칙을 따르도록 유지할 수 있습니다.

※ DRY 원칙: Do not Repeat Yourself, 불필요하게 중복되는 코드를 방지 하는 소프트웨어 개발 원칙

즉, ExecutionContext 객체의 유무로 가드와 미들웨어의 차이가 발생하는 것으로 봐도 무방한 것이다. 그렇다면, 여기서 언급되는 ExecutionContext는 무엇일까??

ExecutionContext (실행 컨텍스트)

너무 길게 언급하면 글이 너무 산으로 가려고 하니 간략하게 이야기하면, NestJS 내에서 사용자의 요청, 반환 정보를 담고 있을 뿐 아니라 해당 요청이 어떤 컨트롤러의 어떤 메서드를 통해 처리되는지에 대한 정보도 담고 있는 객체이다.

이는 지금 다루는 가드 뿐 아니라 향후 다룰 인터셉터, 예외 필터에서도 등장한다. 

 

가드 작성

NestJS에서 가드를 작성하기 위해서는 @Injectable() 데코레이터를 이용한 클래스를 생성해주어야한다. 이 때 생성되는 클래스는 NestJS의 CanActivate를 상속해야하고, 내부적으로는 canActivate 메서드를 생성해주어야한다. 해당 메서드에서 ExecutionContext를 파라미터로 이용하여 사용자의 권한을 확인하고, 최종적으로는 boolean 타입을 반환하여 요청을 내부 핸들러에 전달할지, 아니면 403(Forbidden)을 곧바로 반환하게 할지에 대한 판단이 이루어진다. 

아래는 약식으로 작성한 모든 요청을 통과시키는 TestGuard이다.

import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
import { Observable } from 'rxjs';

@Injectable()
export class TestGuard implements CanActivate {
  canActivate(
    context: ExecutionContext,
  ): boolean | Promise<boolean> | Observable<boolean> {
    return true; // 모든 요청을 통과시키는 가드
  }
}

 

가드 적용

가드를 적용하는 방법은 크게 3가지가 존재한다.

1. 모듈 밖에서 작동하는 전역 가드
2. 모듈 내에서 작동하는 전역 가드
3. 특정 컨트롤러에 대해 작동하는 가드

모듈 밖에서 작동하는 전역 가드

해당 방식은 useGlobalGuards()라는 NestJS 애플리케이션의 메서드를 이용한다. 이는 전역 미들웨어의 적용 방식과 비슷한데, 해당 방식을 이용하면 마찬가지로 의존성을 활용할 수 없다.

import { NestFactory } from '@nestjs/core';
import { TestGuard } from './app.guard';
import { AppModule } from './app.module';

async function bootstrap() {
  // NestJS 애플리케이션 인스턴스
  const app = await NestFactory.create(AppModule);
  app.useGlobalGuards(new TestGuard()); // 클래스가 아닌 인스턴스 형태로 인자에 포함시켜야 함
  await app.listen(3000);
}
bootstrap();

 이 때 해당 방식을 이용하기 위해서는 메서드에 가드를 인스턴스 형태로 넣어주어야 한다.

모듈 내에서 작동하는 전역 가드

전역 가드를 모듈 밖에서 적용할 경우 의존성을 사용할 수 없기 때문에, 이를 해결하기 위한 방법으로 다음과 같이 전역 가드 설정을 해줄 수도 있다.

import { Module } from '@nestjs/common';
import { APP_GUARD } from '@nestjs/core';
import { AppController } from './app.controller';
import { TestGuard } from './app.guard';
import { AppService } from './app.service';

@Module({
  imports: [],
  controllers: [AppController],
  providers: [
    { // 전역 가드 설정
      provide: APP_GUARD, 
      useClass: TestGuard 
    }, 
    AppService
  ],
})
export class AppModule {}

특정 컨트롤러에 대해 작동하는 가드

@UseGuards() 데코레이터를 활용하면 특정 컨트롤러에만 가드를 적용할 수 있다.

import { Controller, Get, UseGuards } from '@nestjs/common';
import { TestGuard } from './app.guard';
import { AppService } from './app.service';

@Controller()
@UseGuards(TestGuard)
// @UseGuards(new TestGuard())도 가능
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get('test')
  getHello(): string {
    return this.appService.getHello();
  }

  @Get('test2')
  getTest(): string {
    return this.appService.getBye();
  }
}

@UseGuards()의 인자로는 Guard 클래스가 올 수도, 혹은 해당 클래스를 활용하여 생성된 인스턴스가 올 수도 있다.

또한 컨트롤러 전체가 아닌 컨트롤러 내 특정 메서드에 대해서만 적용하는 것도 가능하다. 예시는 다음과 같다.

import { Controller, Get, UseGuards } from '@nestjs/common';
import { TestGuard } from './app.guard';
import { AppService } from './app.service';

@Controller()
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get('test')
  @UseGuards(TestGuard) // test 경로에 대해서만 가드 적용
  getHello(): string {
    return this.appService.getHello();
  }

  @Get('test2')
  getTest(): string {
    return this.appService.getBye();
  }
}

이를 이용하면 우선 컨트롤러 전체에 특정 가드를 적용시키고, 특정 메서드에 대해서는 따로 다른 가드를 적용하는 방식 (override)로도 활용이 가능하다. 

여기까지 따라왔다면 NestJS 프로젝트에 가드를 적용할 수 있지만, 아직은 반쪽짜리에 불과하다. 왜냐하면 ExecutionContext를 아직 활용하고 있지 않기 때문이다! 

 

가드에서 ExecutionContext 활용

앞에서 언급했듯이, NestJS에서 가드와 미들웨어의 차이는 ExecutionContext의 유무로 갈리며 이를 적절히 활용하는 것은 매우 중요하다.

그렇다면 어떻게 활용할 수 있을까? 

우선, ExecutionContext의 getClass()와 getHandler() 메서드가 반환하는 것은 해당 요청이 처리될 컨트롤러 클래스와 메서드에 지나지 않는다. 이를 활용하기 위해서는 프로그래머가 직접 핸들러에 특정 메타데이터(가령, 핸들러에 접근할 수 있는 권한)를 등록하고, 가드에서는 ExecutionContext를 이용하여 요청하는 핸들러의 권한을 사용자의 권한과 비교할 수 있다. 이를 도와주는 것이 바로 NestJS의  SetMetadata이다. 

SetMetadata

NestJS의 SetMetadata는 기본적으로 데코레이터로 활용할 수 있지만, 이를 직접 이용하여 데코레이팅하는 방식은 권장하지 않는다고 한다. 대신 이를 활용하여 아래와 같이 커스텀 데코레이터를 만드는 것을 추천하고 있다.

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

// SetMetadata(key, value)
// 핸들러에 추가할 메타데이터를 키, 밸류 형식으로 부여
// 각 핸들러의 접근 권한 메타데이터를 부여하는 데코레이터 생성
export const Roles = (...roles: string[]) => SetMetadata('roles', roles);

위 코드는 핸들러에 'roles'라는 키를 이용하여 해당 핸들러에 대한 접근 권한을 설정해주는 커스텀 데코레이터를 선언해준 것이다.

이제 이를 이용하여 위 예시의 getHello() 핸들러에 'admin'(관리자) 권한을 부여하겠다.

import { Controller, Get } from '@nestjs/common';
import { AppService } from './app.service';
import { SetMetadata } from '@nestjs/common';

// SetMetadata(key, value)
// 핸들러에 추가할 메타데이터를 키, 밸류 형식으로 부여
// 각 핸들러의 접근 권한 메타데이터를 부여하는 데코레이터 생성
export const Roles = (...roles: string[]) => SetMetadata('roles', roles);


@Controller()
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get('test')
  @Roles('admin') // getHello() 핸들러에 'roles' -> 'admin' 메타데이터 부여
  getHello(): string {
    return this.appService.getHello();
  }
}

위와 같이 작성해주면 핸들러에 접근 권한을 메타데이터로 추가해준 것이다. 마지막으로 할 일은, 이제 가드에서 설정해 준 메타데이터를 읽고, 사용자의 요청에 이에 부합하는 인증 데이터가 포함되어 있는지 확인해주면 된다!

Reflector를 이용한 메타데이터 접근

추가해둔 메타데이터에 접근하기 위해서는 NestJS에서 제공되는 Reflector를 가드에 의존성 주입하고 이를 활용해야 한다. 이를 통해 타깃 핸들러의 'roles'->'admin' 이라는 메타데이터를 가져온 후, request에 포함된 유저의 권한이 이에 부합하는지 확인하면 된다. 최종적인 코드는 다음과 같다.

// app.guard
import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { Observable } from 'rxjs';

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

  canActivate(
    context: ExecutionContext,
  ): boolean | Promise<boolean> | Observable<boolean> {
    const roles = this.reflector.get<string[]>('roles',context.getHandler());
    
    // 만약 권한 요구가 따로 없다면 곧바로 가드 통과
    if (!roles) {
        return true;
    }

    const request = context.switchToHttp().getRequest();
    const userRole = request.user.role;

    // 만약 유저의 권한이 메타데이터에 포함된다면 true, 그렇지 않다면 false
    return roles.includes(userRole);
  }
}

// app.controller
import { Controller, Get, UseGuards } from '@nestjs/common';
import { TestGuard } from './app.guard';
import { AppService } from './app.service';
import { SetMetadata } from '@nestjs/common';

// SetMetadata(key, value)
// 핸들러에 추가할 메타데이터를 키, 밸류 형식으로 부여
// 각 핸들러의 접근 권한 메타데이터를 부여하는 데코레이터 생성
export const Roles = (...roles: string[]) => SetMetadata('roles', roles);


@Controller()
@UseGuards(TestGuard)
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get('test')
  @Roles('admin')
  getHello(): string {
    return this.appService.getHello();
  }

  @Get('test2')
  getTest(): string {
    return this.appService.getBye();
  }
}

가드 내 로직의 흐름은 다음과 같다.

1. 타깃 핸들러 내 권한 요청이 없다면 바로 통과
2. 권한 요청이 존재할 경우, 사용자의 권한 확인
3. 사용자의 권한이 메타데이터에 부합하는 경우 true, 그렇지 않다면 false 반환