NGINX Plus API Gateway JWT Token 만료기간 설정 방법

NGINX Plus API Gateway는 강력한 API Gateway 솔루션으로 JWT(JSON Web Token)를 사용하여 인증 및 인가를 구현할 수 있습니다. 하지만, JWT Token은 일정 시간이 지나면 만료되기 때문에, 이를 처리해주는 것이 중요합니다.

이번 포스트에서는 NGINX Plus API Gateway 솔루션에서 JWT Token 만료기간 을 설정하는 방법에 대해 설명하겠습니다.
※ JSON Web Token(JWT)은 선택적 서명 및 암호화를 사용하여 데이터를 만들기 위한 인터넷 표준입니다. 정보를 JSON 포맷으로 생성한 암호화된 토큰으로 String 형태로 저장되어있습니다.

목차

1. JWT (JSON Web Token) 개요
2. JWT의 구조
3. JWT 동작 원리
4. JWT Token 만료기간 설정
5. JWT Token 만료기간 테스트 시작하기

1. JWT (JSON Web Token) 개요

JWT (JSON Web Token)는 웹 애플리케이션과 API 간에 정보를 안전하게 전송하기 위한 인증 및 인가 방식 중 하나입니다. JWT는 JSON 객체로 이루어져 있으며, 이 객체는 claim(클레임)이라는 이름의 속성들로 구성됩니다.

JWT는 일반적으로 세 가지 부분으로 구성됩니다.

  1. Header(헤더): JWT의 타입 및 해싱 알고리즘 정보를 포함합니다.
  2. Payload(페이로드): JWT에 포함되는 클레임 정보를 포함합니다. 클레임에는 등록된 클레임, 공개 클레임, 비공개 클레임이 있습니다. 등록된 클레임은 이미 정의된 속성으로, 예를 들어, 발행자(issuer), 만료 시간(expiration time), 주제(subject) 등이 있습니다. 공개 클레임은 사용자 정의 속성이며, 이름은 충돌을 방지하기 위해 URI 형식으로 지정됩니다. 비공개 클레임은 발행자와 사용자만 알 수 있는 속성으로, 이름은 URI 형식으로 지정됩니다.
  3. Signature(서명): JWT의 검증을 위한 서명으로, 헤더와 페이로드를 base64로 인코딩한 후, 특정 비밀키를 사용하여 해싱한 값입니다.

JWT는 토큰 기반의 인증 방식 중 하나로, 사용자가 로그인하면 서버는 JWT를 발급하고, 이 JWT를 사용하여 API에 접근할 때마다 검증합니다. JWT는 클라이언트 측에서 저장되기 때문에, 서버는 세션 관리나 쿠키 사용 없이도 사용자 인증을 할 수 있습니다.

JWT의 장점은 다음과 같습니다.

  • 토큰 기반의 인증 방식으로, 서버에 대한 부하가 감소됩니다.
  • 서버와 클라이언트 간의 상태를 유지할 필요가 없어집니다.
  • 정보를 JSON 객체로 전달하므로, 데이터 형식 변환에 대한 부담이 줄어듭니다.

하지만, JWT를 사용할 때 주의해야 할 점도 있습니다. 특히, JWT는 한 번 발급되면 만료되기 전까지는 계속 사용할 수 있기 때문에, 중요한 정보를 담은 JWT가 탈취되면 보안에 취약해질 수 있습니다. 이를 방지하기 위해 JWT의 만료 기간을 설정하고, SSL을 사용하여 안전한 통신을 보장해야 합니다.

2. JWT의 구조

JWT(JSON Web Token)는 3개의 파트(Part)로 구성되어 있습니다.

  1. Header(헤더): JWT의 타입 및 해싱 알고리즘 정보를 포함합니다. 이 파트는 JSON 객체로 이루어져 있으며, 일반적으로 다음과 같은 정보를 포함합니다.
    • typ: JWT의 타입을 지정합니다. 일반적으로 JWT를 사용하므로 “JWT”로 지정합니다.
    • alg: JWT의 해싱 알고리즘을 지정합니다. 대표적으로 HMAC SHA256, RSA SHA256, ECDSA SHA256 등이 있습니다.
    이 파트는 Base64로 인코딩되어 전송됩니다.
  2. Payload(페이로드): JWT에 포함되는 클레임 정보를 포함합니다. 클레임은 JWT에 담긴 정보를 표현하는 이름-값 쌍입니다. 이 파트는 JSON 객체로 이루어져 있으며, 일반적으로 다음과 같은 정보를 포함합니다.
    • Registered claims: JWT에서 정의한 특별한 클레임으로, 발행자(issuer), 주제(subject), 만료 시간(expiration time) 등이 있습니다.
    • Public claims: 사용자가 정의한 클레임으로, 이름은 URI 형식으로 지정됩니다.
    • Private claims: 발행자와 사용자만 알 수 있는 클레임으로, 이름은 URI 형식으로 지정됩니다.
    이 파트는 Base64로 인코딩되어 전송됩니다.
  3. Signature(서명): JWT의 검증을 위한 서명으로, 헤더와 페이로드를 합친 문자열에 대한 서명값입니다. 이 파트는 다음과 같이 생성됩니다.
    • 지정된 해싱 알고리즘으로 헤더와 페이로드를 합친 문자열을 해싱합니다.
    • 발급자가 가지고 있는 비밀키를 사용하여 해당 해시값을 서명합니다.
    이 파트는 Base64로 인코딩되어 전송됩니다.

따라서, JWT는 다음과 같이 구조화되어 있습니다.

[Base64Url encoded header].[Base64Url encoded payload].[Base64Url encoded signature]

예를 들어, JWT의 헤더와 페이로드가 각각 다음과 같은 JSON 객체이고, HMAC SHA256 알고리즘과 “my_secret”이라는 비밀키를 사용하여 서명한 경우,

Header:

{
  "alg": "HS256",
  "typ": "JWT"
}

Payload:

{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022
}

JWT는 다음과 같은 형식을 가집니다.

eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJzdWIiOiAiMTIzNDU2

JWT는 세 파트로 구분되어지고, 각 파트는 . 으로 구분하여 표현됩니다. 또한 URL에서 파라미터로 사용할 수 있도록 하기 위해 base64 인코딩을 사용합니다.

3. JWT 동작 원리

JWT의 동작 원리는 다음과 같습니다.

  1. 사용자가 로그인을 시도하면 서버는 사용자의 ID와 Password를 확인합니다.
  2. 사용자의 ID와 Password가 유효하면 서버는 해당 사용자의 정보를 기반으로 JWT를 생성합니다.
  3. 생성된 JWT는 서버에서 클라이언트로 전달됩니다.
  4. 이후 클라이언트에서 서버로 요청을 보낼 때마다, 해당 요청의 헤더에 JWT를 포함시킵니다.
  5. 서버는 해당 JWT가 유효한지 확인한 후, 요청에 대한 응답을 반환합니다.
  6. JWT의 유효기간이 만료되면, 클라이언트는 서버에 새로운 JWT를 요청해야 합니다.

즉, JWT는 사용자 인증을 위해 필요한 정보들을 JSON 형태로 암호화한 문자열입니다. 이 문자열은 서버에서 생성된 후 클라이언트에게 전달되어, 클라이언트에서는 이를 저장해 두었다가 필요할 때마다 서버에 전달합니다. JWT를 이용하면 서버는 사용자 인증과정을 간소화할 수 있고, 클라이언트와 서버 간의 상태 정보를 유지할 필요가 없어집니다.

4. JWT Token 만료기간 설정

일반적으로 JWT Token 만료기한 설정은 JWT의 Payload 부분의 클레임인 iat(JWT가 발급된 타임스탬프 지정) 와 exp(JWT가 만료되도록 설정된 시간을 지정) 을 설정하여 기간을 정할 수 있습니다.

하지만 NGINX Plus 를 사용하게 되면 NGINX Plus는 exp 클레임을 자동으로 검증되게 할 수 있습니다. map 지시문 다음 auth_jwt_require 지시문을 사용하여 검증할 수 있습니다.

map $jwt_claim_iss $valid_jwt_iss {
    "good" 1;
}
...
 
auth_jwt_require $valid_jwt_iss;

이 값에는 텍스트, 변수 두가지의 조합을 포함할 수 있으며, 모든 값이 비어 있지 않고 “0”이 아니어야 검증이 성공합니다.

ngx_http_auth_jwt_module 모듈은 임베디드 변수를 지원하며 그중 $jwt_claim_name은 지정된 JWT 클레임 값을 반환 합니다.

Note: 중첩 클레임과 점(“.”)을 포함한 클레임의 경우, 변수 값을 평가할 수 없습니다. 대신 auth_jwt_claim_set 명령을 사용해야 하며 JWE로 암호화된 토큰에 대한 변수 값은 액세스 단계에서 복호화된 이후에만 사용할 수 있습니다.

즉, payload exp값을 ngx_http_auth_jwt_module 변수를 사용하여 받아온뒤 map 지시문과 auth_jwt_require 지시문을 사용하여 0이 아니면 인증이 성공하고 0이 되면 인증이 거부되는 것으로 설정 할 수 있습니다.

5. JWT Token 만료기간 테스트 시작하기

NGINX Plus API Gateway와 JWT 토큰을 통합하여 사용해 보거나 테스트해 보려면 지금 30일 무료 평가판을 신청하거나 사용 사례에 대해 최신 소식을 빠르게 전달받고 싶으시면 아래 뉴스레터를 구독하세요.