본문으로 건너뛰기

JWT Policy

개요​

JWT (JSON Web Token) 정책은 API 요청에 포함된 토큰을 검증하는 데 사용됩니다. 이 정책은 올바른 JWT KEY와 SECRET을 사용하여 생성된 유효한 토큰을 가진 사용자만 API에 접근할 수 있도록 보장합니다.

이 정책은 RequiredPath 또는 NotRequiredPath 모드를 사용하여 선택된 경로에 대한 토큰 검증을 지원합니다. 또한, 로그아웃 시 토큰을 무효화하기 위해 tokenBlacklistLogoutPath 함수와 결합할 수 있습니다.

지원되는 알고리즘:

  • HS256 (HMAC SHA-256)
  • RS256 (RSA SHA-256)

JWT 토큰 규칙​

APIM에서 JWT 토큰을 성공적으로 인증하려면:

  • JWT 토큰은 Authorization 헤더에 포함되어야 합니다:
Authorization: bearer JWT_TOKEN
  • 토큰의 페이로드는 다음을 포함해야 합니다:
    • "apim_key_claim_name" 프로젝트의 JWT KEY.
    • "exp" 필드로 토큰 만료 시간을 나타냅니다.

예시 페이로드:

"apim_key_claim_name": "64c44d593be841bcec7fe768184e4c7e",
"exp": 1900000000

예시 헤더:

"alg": "HS256",
"typ": "JWT"

JWT 샘플 토큰:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcGltX2tleV9jbGFpbV9uYW1lIjoiNjRjNDRkNTkzYmU4NDFiY2VjN2ZlNzY4MTg0ZTRjN2UiLCJleHAiOjE5MDAwMDAwMDB9.1kB5k-vM2Cef7ZYTyJUQ-LsDUmG4K7sJUfrJ3FqgYxQ

구성 세부정보​

JWT 경로 매칭​

JWT 검증은 두 가지 모드를 사용하여 선택된 경로에 적용할 수 있습니다:

Option Description
RequiredPath나열된 메서드/경로 쌍에만 JWT 인증을 적용합니다. 다른 모든 경로는 JWT가 필요하지 않습니다.
NotRequiredPath나열된 경로를 제외한 모든 경로에 JWT 인증을 적용합니다.
노트

한 번에 하나의 모드(RequiredPath 또는 NotRequiredPath)만 사용할 수 있습니다. 모드를 전환하면 이전 설정이 초기화됩니다.

입력 형식:

Method_Path

예시:

GET_/v1/test
/v1/test에서 GET 요청에 적용됩니다.
POST_/v1/example
/v1/example에 대한 POST에 적용됩니다.
ANY_/v1/apis
/v1/apis에 대한 모든 HTTP 메서드에 적용됩니다.
GET_/v1/apis*
/v1/apis 아래의 모든 하위 경로에 적용됩니다 (예: /v1/apis/a)

tokenBlacklistLogoutPath​

이 기능은 로그아웃 요청이 이루어질 때 APIM이 JWT 토큰을 블랙리스트에 추가할 수 있도록 하며, API 게이트웨이에서 HTTP 200을 성공적으로 반환합니다.

Toggle Field:

FieldDescription
useJWTBlacklistRevoking활성화되면, 로그아웃 응답 시 JWT 토큰이 블랙리스트 저장소에 추가됩니다. 이는 동일한 토큰의 추가 사용을 방지합니다.
노트

변경할 수 없음: 이 정책이 제거되지 않도록 방지하는 토글입니다.

설정 값 변경 불가: 설정 후 구성 값 변경을 방지하는 토글입니다.

Redis Configuration (used to store blacklisted tokens)​

옵션 1: APIMRedis - 기본 시스템 Redis; 수동 구성 필요 없음.

옵션 2: CustomRedis

Configuration FieldDescription
Redis HostRedis 서버의 주소 (예: 127.0.0.1).
Redis PortRedis 서버의 포트 번호 (예: 6379).
Redis Password인증을 위한 비밀번호.
Redis Database사용할 데이터베이스 인덱스를 지정합니다 (예: 1).
Redis Pool SizeRedis 연결 풀의 최대 연결 수 (기본값: 1000).
Redis Pool Backlog사용 가능한 연결을 기다리는 최대 요청 수 (기본값: 30).

옵션 3: RedisCluster

Configuration FieldDescription
Redis Cluster Nodes클러스터 노드 주소 (예: redis-cluster.apim:6379).
Redis Cluster Password인증을 위한 비밀번호.
Redis Cluster Name클러스터 이름을 지정합니다 (예: kong_redis_cluster).
Redis Connect TimeoutRedis 연결을 설정하기 위한 타임아웃 (기본값: 1000ms).
Redis Read TimeoutRedis에서 데이터를 읽기 위한 타임아웃 (기본값: 1000ms).
Redis Send TimeoutRedis에 데이터를 전송하기 위한 타임아웃 (기본값: 1000ms).
Redis Pool SizeRedis 연결 풀에서 최대 연결 수 (기본값: 1000).
Redis Pool Backlog최대 대기 중인 연결 수 (기본값: 30).
Redis Keepalive TimeoutRedis 연결이 닫히기 전 최대 유휴 시간 (기본값: 55000ms).