JWT 토큰 디코딩 완벽 가이드 - 구조 분석부터 안전한 활용법까지 정리
JWT 토큰의 헤더, 페이로드, 시그니처 세 부분 구조를 분석하고, 안전하게 디코딩하는 방법과 보안 주의사항, 실전 활용 팁까지 개발자가 알아야 할 핵심을 정리합니다.
API 개발을 하다 보면 JWT 토큰을 자주 마주치게 됩니다. 인증 요청 응답으로 받은 토큰의 내용이 궁금하거나, 만료 시간을 확인해야 하는데 알파벳과 숫자가 뒤섞인 긴 문자열이라 답답했던 경험이 있을 겁니다. JWT는 단순한 랜덤 문자열처럼 보이지만, 실제로는 Base64URL로 인코딩된 세 부분으로 구성되어 있어 디코딩만 하면 누구나 내용을 확인할 수 있습니다.
JWT 토큰이란 무엇인가
JWT(JSON Web Token)는 당사자 간 정보를 JSON 객체로 안전하게 전송하기 위한 개방형 표준입니다. RFC 7519로 표준화되어 있으며, 주로 사용자 인증과 정보 교환에 활용됩니다. 최근 REST API와 SPA 구조가 보편화되면서 세션 대신 JWT를 쓰는 서비스가 빠르게 늘어났습니다.
JWT의 가장 큰 특징은 자체적으로 정보를 담고 있다는 점입니다. 서버가 별도로 세션 정보를 저장하지 않아도 토큰 자체에 사용자 식별 정보, 권한, 만료 시간 등이 포함되어 있어 분산 환경과 마이크로서비스 아키텍처에서 유리합니다.
JWT 토큰 구조 분해하기
JWT는 점(.)으로 구분된 세 부분으로 이루어져 있습니다. xxxxx.yyyyy.zzzzz 형태이며, 각각 헤더, 페이로드, 시그니처를 의미합니다. 점을 기준으로 잘라서 앞 두 부분만 Base64URL 디코딩하면 즉시 JSON 데이터를 얻을 수 있습니다.
헤더(Header)
헤더에는 토큰의 타입과 사용된 서명 알고리즘 정보가 들어 있습니다. 보통 {"alg":"HS256","typ":"JWT"} 같은 형태이며, HS256, RS256, ES256 같은 알고리즘이 자주 사용됩니다.
페이로드(Payload)
페이로드에는 클레임(Claim)이라 부르는 실제 데이터가 담깁니다. RFC 7519가 정의하는 표준 클레임은 다음과 같습니다.
- iss: 토큰 발급자(Issuer)
- sub: 토큰 주체(Subject), 일반적으로 사용자 ID
- exp: 만료 시간(Expiration Time), Unix 타임스탬프 형식
- iat: 발급 시간(Issued At), Unix 타임스탬프 형식
- aud: 토큰 대상자(Audience)
시그니처(Signature)
시그니처는 헤더와 페이로드가 변조되지 않았음을 검증하는 부분입니다. 헤더에 명시된 알고리즘과 서버의 비밀 키를 사용해 생성되며, 키를 모르면 동일한 시그니처를 만들어낼 수 없습니다.
JWT 토큰 디코딩하는 방법
JWT 디코딩은 생각보다 단순합니다. 토큰을 점(.)으로 나눈 뒤 앞 두 부분을 Base64URL로 디코딩하면 됩니다. 명령줄 한 줄로도 충분히 확인할 수 있고, 별도의 라이브러리 없이도 처리 가능합니다.
JWT 디코딩과 서명 검증은 다릅니다. 디코딩으로는 내용만 확인할 수 있고, 토큰의 진위 여부는 시그니처 검증을 거쳐야 보장됩니다. 운영 환경 인증 로직에서는 두 과정을 반드시 함께 수행해야 합니다.
온라인 도구를 사용하면 가장 빠르게 확인할 수 있습니다. jwt.io는 가장 널리 쓰이는 디버거로, 토큰을 붙여 넣으면 즉시 헤더와 페이로드 내용을 보여줍니다. 다만 운영 환경에서 발급된 실제 토큰을 외부 사이트에 붙여 넣는 행위는 토큰 유출 위험이 있으므로 학습이나 테스트 토큰에만 사용하는 것이 안전합니다.
로컬에서 빠르게 확인하고 싶다면 터미널 한 줄 명령으로도 가능합니다. JWT의 페이로드는 결국 Base64URL 형식이므로, 일반적인 Base64 인코더 도구로 가운데 부분만 디코딩해도 동일한 JSON을 얻을 수 있습니다. Base64URL은 표준 Base64와 비교해 +와 /가 -와 _로 바뀐 변형이라, 변환 후 디코딩하거나 패딩(=)만 신경 쓰면 됩니다.
디코딩 도구 비교
JWT 디코딩에 사용할 수 있는 도구는 다양합니다. 사용 환경과 목적에 맞게 선택하면 됩니다.
| 도구 | 장점 | 단점 | 추천 사용처 |
|---|---|---|---|
| jwt.io | UI 직관적, 서명 검증 가능 | 외부 서버 전송 우려 | 학습, 테스트 토큰 |
| CLI(jq, openssl, base64) | 로컬 처리, 빠름 | 초기 학습 필요 | 운영 환경, 자동화 스크립트 |
| 브라우저 확장 | 개발자도구 통합 | 확장 권한 신뢰 필요 | 웹 개발 디버깅 |
| 언어별 라이브러리 | 코드 내 통합 가능 | 의존성 추가 부담 | 애플리케이션 개발 |
echo "토큰값" | cut -d "." -f2 | base64 -d 한 줄로 페이로드를 즉시 확인할 수 있습니다. 패딩 오류가 나면 끝에 ==를 붙이거나 base64 -d -i 옵션을 사용하면 해결됩니다.만료 시간(exp) 해석과 시간 변환
JWT 페이로드의 exp 필드는 Unix 타임스탬프(1970년 1월 1일 00:00 UTC부터 흐른 초 단위)로 표시됩니다. 예를 들어 exp 값이 1779580800이라면 이는 2026년 5월 24일 00:00 UTC를 의미합니다. 사람이 바로 읽기는 어려운 형식입니다.
한국에서 토큰을 디버깅할 때는 KST(UTC+9) 기준으로 변환해야 정확한 만료 시각을 알 수 있습니다. 타임스탬프를 사람이 읽을 수 있는 시간 형식으로 빠르게 바꾸려면 단위 변환기의 시간 변환 기능을 활용하는 것도 한 가지 방법입니다. 별도 코드를 작성하지 않아도 즉시 KST로 환산된 값을 확인할 수 있어 토큰 만료 디버깅에 유용합니다.
JWT 토큰 디코딩 시 보안 주의사항
JWT를 다룰 때 자주 발생하는 실수와 보안 위험을 정리하면 다음과 같습니다.
- 실제 운영 토큰을 외부 사이트에 붙여 넣지 말 것: 토큰이 유효한 동안 누군가 가로채면 사용자 권한으로 그대로 API 호출이 가능합니다.
- 민감 정보를 페이로드에 담지 말 것: 페이로드는 누구나 디코딩할 수 있는 공개 정보로 취급해야 합니다.
- 알고리즘 none 공격 주의: 일부 라이브러리는 alg가 none으로 설정된 토큰을 그대로 받아들이는 취약점이 있습니다. 서버에서 허용 알고리즘을 명시적으로 지정해야 합니다.
- 만료 시간 검증 누락: 디코딩만 하고 exp를 확인하지 않으면 만료된 토큰도 통과시킬 수 있습니다. 토큰 검증 시 exp와 nbf(Not Before)도 반드시 확인해야 합니다.
실제 서비스 코드에서는 디코딩과 검증을 함께 수행하는 검증된 라이브러리(jsonwebtoken, PyJWT, jjwt 등)를 사용하는 것이 안전합니다. 직접 Base64 디코딩만 수행하면 시그니처 검증 단계를 빠뜨리기 쉽고, 결과적으로 위조 토큰에 무방비 상태가 됩니다.
지금 다루고 있는 토큰을 한번 디코딩해보고, exp 값을 KST로 변환해 만료 시점을 직접 확인해보시기 바랍니다. 그 다음 단계로 시그니처 검증까지 구현해보면 JWT 기반 인증 구조를 완전히 이해할 수 있습니다.
