[Swagger] BasicAuth 문서 접근 보안

NestJS 에서는 @nestjs/swagger 패키지를 통해 API Swagger docs 를 만들 수 있다.
해당 패키지에 대한 기본적인 가이드는 [공식문서] 를 참조하자.

서버에서 API 를 구현하면서 몇가지 설정을 동봉하면 Swagger 가 자동생성되는데,
이를 통해 개발된 API 에 대한 호출을, 정의한 타입들을 운용하여 실행 및 테스트해볼 수 있다.

NestJS Swagger 문서는 서버랑 같이 실행되면서 serve 되기 때문에 서버 엔드포인트의 특정 경로를 기반으로 제공된다. 그러다보니, 클라이언트 개발자나 외부 인원에게 공유하기 위해 만든 이 문서가 서버 경로를 아는 누군가에 의해 노출될 수 있는 것이다.

예를 들어, Swagger 를 "/api-docs" 라고 하는 경로 하위에 설정하였다면,
서버가 배포된 환경에서, "https://서버.예시.주소/api-docs" 와 같은 접근 가능한 상태가 될 것이기에,
서버 주소를 알게 된 누군가(혹은 공격성을 띈 누군가)에 의해 마구마구 접근될 수 있는 것이다.

 

그래서 API Swagger 문서(즉, 서버의 특정 경로)에 대한 접근 보안을 걸어주기로 했다.

물론 NestJS 자체에서 제공하는 Guard 등의 설정을 통해 API 자체에 대한 호출(실행)을 막아줄 수 는 있으나, 누군가 모르는 사람이 내가 배포해둔 서버의 Swagger 에 들어와 API 목록들을 찬찬히 구경하고 간다는 것은 여간 꺼림칙할 수 있다.

 

나는 보안을 위해 사용할 수 있는 쉬운 패키지 중 하나인 exporess-basic-auth 패키지를 채택했다.
Express 에서 특정 Route 경로에 대한 보안을 유저/비밀번호 형태로 처리할 수 있는 패키지다.

npm : express-basic-auth 에서 이 패키지를 확인할 수 있다. 더 궁금한 점이 있다면 이곳에서 제공하는 자료를 확인해보자.

 

# 1. express-basic-auth 패키지 설치

일단 당연하게도 Swagger 를 사용하고 있어야 한다. 위에 언급하였던 공식문서를 기반으로 설정하자.

설치와 설정은 간단하다.
일단 프로젝트 영역에 해당 패키지를 설치한다. 자신의 패키지매니저에 따라서 설치하자.

        

          
          
          
          
        
# NPM 이라면
npm install express-basic-auth

# YARN 이라면
yarn add express-basic-auth

 

# 2. 유저/비밀번호 환경변수 설정

이제 지정할 유저와 비밀번호만을 설정하면 되는데, 당연스럽게 보안을 위한 설정이므로 환경변수로부터 안전하게 가져오는게 좋다.

NestJS 에서 환경변수는 @nestjs/config 의 메커니즘이나 dotenv 등 다양한 방식으로 가져올 수 있는데, 자신의 프로젝트에 설정되어 있는 환경을 응용하여 환경변수를 설정하고 가져오면 되겠다.

 

# 3. 애플리케이션 설정

환경변수를 통해 유저, 비밀번호 값이 설정되었다고 가정한다면, 이제 main.ts 메인 실행파일을 수정하여 해당 보안을 걸어주도록 하자.

NestJS 실행파일에서는 기본적으로 아래와 같은 애플리케이션을 생성하고 실행시킨다.
(NestJS 공식 보일러플레이트에서 제공하는 코드)

        

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

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}
bootstrap();

여기서 app 이 생성/실행되는 애플리케이션이기 때문에, 이에 대한 Swagger 설정을 해야 한다.
app.use 함수를 이용하여 해당 Swagger 에 주입될 경로에게 BasicAuth 를 걸어주면 된다.

 

아래에 main.ts 실행에 적용한 예시 코드가 있다.

main.ts

코드를 살펴보면 환경변수 설정 영역과 Swagger 설정 영역으로 나뉘며, Swagger 설정에서는 보안 설정과 실제 문서 설정으로 영역이 나뉜다.

 

        

          
          
          
          
        
/**
 * 환경변수 영역
 */
const username = 'user';
const password = 'password';
const path = 'docs';

환경변수 영역은 다양한 방법을 통해 설정할 Swagger 제공주소, 접근 유저이름, 비밀번호 설정 값을 나타낸다.

 

        

          
          
          
          
        
// Swagger 보안 설정
app.use(
    [`/${path}`],
    expressBasicAuth({
        challenge: true,
        users: {
            [username]: password,
        },
    }),
);

Swagger 보안 설정 영역은 다운로드한 express-basic-auth 패키지의 사용법을 나타낸다. app 애플리케이션에 이 설정을 하게 되는데, 아래 사항들을 주의하도록 하자.

• 첫번째 인자값은 서버 애플리케이션에서 Swagger 문서가 나타나는 경로를 지정한다.
  이 때, 경로 가장 앞에 / 값이 없다면 추가해주자.
• 두번째 인자값에 설정하는 BasicAuth 보안이 들어간다.
  접근하는데 허용해줄 유저-비밀번호 Pair 를 object key-value 형식으로 넘겨주면 된다.

 

        

          
          
          
          
        
// Swagger 설정
const config = new DocumentBuilder().build();
const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup(path, app, document);

Swagger 설정 영역은 예시로 작성한 것이므로, 실행은 되나 구체적인 설정들이 동반되어 있지 않다.
앞서 제공한 공식문서나 @nestjs/swagger 패키지 사용법들을 참고하자.

 

이렇게 설정해준 뒤, 위 소스코드를 기반으로 서버 애플리케이션을 실행시켜보자.
그리고 3000 포트로 serve 되므로 http://localhost:3000/docs 경로로 들어가보자.

경로 접근 시 로그인 요구

로그인 후 Swagger 화면

로그인에 성공하면 Swagger 문서에 접근할 수 있게 된다.