Nest.js Swagger Bearer 인증 적용

Authentication Bearer 이란

Bearer Authentication 또는 Bearer Token Authentication은 HTTP 인증 스키마 중 하나로, 주로 OAuth 2.0 또는 JWT (JSON Web Token)와 같은 토큰 기반 인증에서 사용됩니다. 이 방식은 서버에 요청을 보낼 때 Authorization 헤더를 사용하여 토큰을 전달하는 방법을 말합니다.

헤더는 대략 다음과 같은 형태를 가집니다.

Authorization: Bearer YOUR_ACCESS_TOKEN

여기서 Bearer는 이 토큰을 지니고 있는 클라이언트가 요청 권한을 가지고 있음을 나타내는 접두어입니다. 이후에 공백을 두고 실제 토큰 (YOUR_ACCESS_TOKEN)이 옵니다.

서버는 이 헤더를 받아 토큰을 검증하고, 해당 토큰이 유효한 경우 요청을 처리합니다. 토큰이 유효하지 않거나 만료된 경우, 서버는 클라이언트에게 인증 실패 응답을 반환합니다.

Bearer 인증은 상태를 저장하지 않는 (stateless) 방식의 인증입니다. 이는 각 요청마다 토큰을 보내 인증 정보를 전달하므로, 서버는 상태를 유지할 필요가 없습니다. 이 점이 RESTful API에 적합하게 만듭니다. 하지만 토큰이 탈취당하면, 탈취자도 해당 토큰을 이용해 인증할 수 있으므로 보안에 신경을 써야 합니다.

 

Sessoion과 JWT 인증 방식의 차이점을 알고자 하시면 아래글을 참고하시면 되겠습니다.

JWT - Refresh Token, Access Token

 

Swagger Authentication 기능 적용

Swagger는 API 문서를 작성하고 실행하기 위해서 사용되는 라이브러리 입니다. 그러므로 요청마다 Authentication header을 추가 해주어야 합니다. 다음은 swagger 설정 방법입니닫. main.ts에 아래 내용을 추가 해줍니다. 

 

  // Swagger
  const config = new DocumentBuilder()
    .setTitle('NestJS project')
    .setDescription('NestJS project API description')
    .setVersion('1.0')
    .addBearerAuth()
    .build();

  const customOptions: SwaggerCustomOptions = {
    swaggerOptions: {
      persistAuthorization: true,
    },
  };
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('docs', app, document, customOptions);

 

이러한 기능을 적용하게 되면 swagger에는 사진과 같이 반영됩니다. 

 

그리고 Authorize를 클릭하게 되면 토큰을 입력하는 창이 뜨는데 여기서 Bearer은 자동으로 입력이 되고 있으므로 토큰 값만 입력하면 되겠습니다.

 

로그인이 되고 나면 이후에 Authenication 인증이 필요한 엔드포인트에 요청을 보내게 되면 정상적인 작업을 수행하게 될 것입니다.