JWT 디코더 완벽 가이드: 개발자를 위한 JSON 웹 토큰의 모든 것
JSON 웹 토큰(JWT)은 현대 웹 인증과 인가의 핵심이 되었습니다. 싱글 사인온 시스템부터 API 보안까지, JWT는 오늘날의 소프트웨어 생태계 어디에서나 사용됩니다. 그러나 많은 개발자들이 구조, 보안 영향, 취약점으로 이어질 수 있는 미묘한 함정을 완전히 이해하지 않은 채 JWT를 사용하고 있습니다. 이 완벽 가이드는 기본 개념부터 고급 보안 사례까지 JWT에 대해 알아야 할 모든 것을 다룹니다.
JSON 웹 토큰(JWT)이란?
JSON 웹 토큰은 두 당사자 간에 클레임(claims)을 전송하기 위한 컴팩트하고 URL 안전한 형식입니다. RFC 7519에 정의된 JWT는 일련의 명세(클레임)를 JSON 객체로 인코딩한 후 디지털 서명하여 무결성과 진위를 보장합니다. 결과적으로 모든 요청마다 데이터베이스 조회 없이 사용자의 신원이나 권한을 확인하는 데 필요한 모든 정보를 담은 자기 완결적 토큰이 됩니다.
JWT는 다음과 같은 모습입니다:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibm...
언뜻 보면 단순히 긴 인코딩된 문자열처럼 보이지만, 점(.)으로 구분된 세 가지 중요한 정보를 담고 있습니다.
JWT의 세 가지 구성 요소
모든 JWT는 마침표로 구분된 세 개의 Base64URL 인코딩 세그먼트로 구성됩니다:
1. 헤더 (Header)
헤더는 토큰의 유형과 서명에 사용된 알고리즘을 설명하는 JSON 객체입니다:
{
"alg": "HS256",
"typ": "JWT"
}
일반적인 서명 알고리즘에는 HS256(HMAC-SHA256, 공유 비밀을 사용하는 대칭 알고리즘), RS256(RSA-SHA256, 공개/비공개 키 쌍을 사용하는 비대칭 알고리즘), ES256(ECDSA-SHA256, 타원 곡선 암호화를 사용하는 효율적인 비대칭 알고리즘)이 있습니다.
2. 페이로드 (Claims)
페이로드는 클레임을 포함합니다 — 사용자에 대한 명세와 추가 메타데이터입니다. 클레임은 세 가지 유형으로 분류됩니다:
등록된 클레임은 JWT 사양에 의해 사전 정의되며 iss(발급자), sub(주체), aud(대상), exp(만료 시간), nbf(이전 사용 불가), iat(발급 시점), jti(JWT ID)를 포함합니다.
공개 클레임은 JWT 사용자에 의해 정의되며 충돌 방지를 위해 IANA JSON Web Token Claims 레지스트리에 등록하거나 URI와 같은 충돌 방지 이름을 사용해야 합니다.
비공개 클레임은 당사자 간에 합의된 커스텀 클레임으로, 사용자 역할, 권한, 또는 애플리케이션별 데이터 등이 있습니다.
3. 서명 (Signature)
서명은 토큰이 변조되지 않았음을 보장합니다. HS256의 경우 다음과 같이 계산됩니다:
HMACSHA256(
base64UrlEncode(header) + "." + base64UrlEncode(payload),
secret
)
서명이 JWT를 신뢰할 수 있게 만드는 핵심입니다. 비밀 키 없이는 공격자가 서명을 무효화하지 않고 페이로드를 수정할 수 없습니다.
JWT 인증 작동 방식
일반적인 JWT 인증 흐름:
- 로그인: 사용자가 인증 서버에 자격 증명(사용자 이름/비밀번호)을 전송합니다.
- 토큰 생성: 서버가 자격 증명을 검증하고, 사용자 클레임을 포함한 JWT를 생성하고, 비밀 키로 서명한 후 클라이언트에 토큰을 반환합니다.
- 후속 요청: 클라이언트가 각 요청의 Authorization 헤더에 JWT를 포함합니다:
Authorization: Bearer <token>. - 검증: 서버가 JWT 서명을 확인하고 클레임(만료, 발급자, 대상)을 검사한 후 요청을 처리합니다.
이 무상태 접근법은 서버 측 세션 저장소의 필요성을 제거하여, 마이크로서비스 아키텍처, 서버리스 컴퓨팅, 분산 시스템에서 세션 상태를 공유하기 어려운 환경에 특히 적합합니다.
JWT 디코더가 필요한 이유
JWT 디코딩은 현대 인증 시스템을 다루는 개발자의 일상적인 작업입니다:
인증 문제 디버깅: 사용자가 접근 문제를 보고할 때, 첫 번째 단계는 JWT를 디코딩하고 클레임을 검사하는 것입니다. 토큰이 만료되었나요? 예상한 역할이 포함되어 있나요?
API 개발 및 테스트: JWT를 받아들이는 API를 구축할 때, 토큰에 올바른 클레임이 포함되어 있고, 적절한 만료 시간이 있으며, 올바른 알고리즘으로 서명되었는지 확인해야 합니다.
보안 감사: JWT 페이로드를 정기적으로 검사하면 과도한 클레임 데이터, 누락된 만료 시간, 부적절한 알고리즘 선택과 같은 잠재적 보안 문제를 식별하는 데 도움이 됩니다.
일반적인 JWT 보안 취약점
"alg": "none" 공격
일부 JWT 라이브러리는 "alg": "none"인 토큰을 허용하여 서명 검증이 수행되지 않습니다. 공격자는 원하는 클레임으로 JWT를 만들고 알고리즘을 "none"으로 설정하여 인증을 완전히 우회할 수 있습니다. 항상 알고리즘 필드를 검증하고 "none" 알고리즘의 토큰을 거부하세요.
키 혼동 공격
서버가 대칭(HS256)과 비대칭(RS256) 알고리즘을 모두 지원할 때, 공격자가 알고리즘을 RS256에서 HS256으로 변경하고 공개 키로 토큰에 서명할 수 있습니다. 서버에서 허용하는 알고리즘을 명시적으로 지정하여 이를 방지하세요.
불충분한 만료 시간
만료되지 않거나 과도하게 긴 만료 시간의 토큰은 유효한 토큰을 얻은 공격자에게 기회의 창을 만듭니다. 짧은 만료 시간(액세스 토큰의 경우 15-30분)을 사용하고 더 긴 세션을 위해 리프레시 토큰 교체를 구현하세요.
페이로드의 민감한 데이터
JWT 페이로드는 Base64URL로 인코딩되지 않았을 뿐 암호화되지 않습니다. 누구나 비밀 키 없이 페이로드를 디코딩할 수 있습니다. JWT 클레임에 비밀번호, 신용카드 번호 등 민감한 정보를 절대 포함하지 마세요.
프로덕션을 위한 JWT 모범 사례
1. 강력하고 교체 가능한 비밀 사용
대칭 알고리즘(HS256)의 경우 암호학적으로 안전한 난수 생성기로 생성된 최소 256비트(32바이트) 길이의 비밀을 사용하세요. 기존 토큰을 무효화하지 않고 비밀을 변경할 수 있도록 비밀 교체 기능을 구현하세요.
2. 적절한 만료 시간 설정
액세스 토큰은 빠르게 만료되어야 합니다(15-60분). 리프레시 토큰은 더 긴 수명(수일~수주)을 가질 수 있지만 안전하게 저장되어야 하며 해지를 지원해야 합니다.
3. 모든 표준 클레임 검증
서명 외에도 항상 exp(토큰이 만료되었는지?), iss(신뢰할 수 있는 기관에서 발급되었는지?), aud(이 서비스를 위한 토큰인지?), nbf(토큰이 아직 활성화되었는지?)를 확인하세요.
4. 분산 시스템에는 비대칭 알고리즘 선호
여러 서비스가 토큰을 검증해야 할 때는 RS256 또는 ES256을 사용하세요. 비대칭 알고리즘을 통해 서비스는 비밀 서명 키에 대한 접근 없이 공개 키를 사용하여 토큰을 검증할 수 있습니다.
5. 토큰 해지 전략 구현
JWT는 무상태이므로 만료 전에 개별 토큰을 해지하려면 추가 메커니즘이 필요합니다. 일반적인 접근 방식으로는 해지된 토큰 ID의 거부 목록 유지, 리프레시 토큰 교체를 통한 짧은 만료 시간 사용, 보안 컨텍스트가 변경될 때 사용자의 모든 토큰을 무효화하는 토큰 버전 관리 시스템 구현 등이 있습니다.
JWT vs. 세션 기반 인증
JWT 장점: 무상태 운영, 마이크로서비스에 적합, 도메인 간 작동(CORS), 서버 측 저장소 불필요.
세션 장점: 간단한 해지(세션 삭제), 더 작은 요청 오버헤드, 활성 세션에 대한 서버 측 제어.
UtiliZest로 JWT를 즉시 디코딩하고 검사하세요
UtiliZest의 JWT 디코더는 JSON 웹 토큰을 디코딩하고 검사하기 위한 깔끔하고 직관적인 인터페이스를 제공합니다. JWT를 붙여넣으면 디코딩된 헤더, 포맷된 JSON의 페이로드, 서명 정보를 즉시 확인할 수 있습니다. 만료 상태를 강조하고, 클레임 구조를 검증하며, 타임스탬프를 사람이 읽을 수 있는 날짜로 포맷합니다.
모든 처리는 브라우저에서 로컬로 이루어지며, 토큰은 서버로 전송되지 않습니다. 설치나 가입 없이 완전히 무료입니다.