[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 문서에 접근할 수 있게 된다.