JWT 토큰 디코딩 완벽 가이드 - 구조 이해부터 안전한 디코딩 방법과 주의사항까지 총정리
JWT 토큰 디코딩의 원리와 jwt.io, 브라우저 콘솔, 터미널을 활용한 3가지 방법을 정리했습니다. 운영 토큰을 온라인 도구에 붙여넣으면 안 되는 이유와 보안 주의사항까지 확인해 보세요.
API 연동을 하다 보면 서버에서 받은 토큰 안에 어떤 정보가 들어 있는지 확인하고 싶을 때가 있습니다. 로그인은 분명히 성공했는데 권한 오류가 나거나, 토큰이 언제 만료되는지 알 수 없어 답답했던 경험이 한 번쯤 있을 겁니다. 이럴 때 필요한 작업이 바로 JWT 토큰 디코딩입니다. 구조만 이해하면 별도 프로그램 설치 없이 몇 초 만에 토큰 내용을 확인할 수 있습니다.
JWT 토큰이란 무엇인가
JWT(JSON Web Token)는 RFC 7519 표준으로 정의된 토큰 형식입니다. 사용자 인증 정보나 권한 데이터를 JSON 형태로 담아 당사자 간에 전달하기 위해 만들어졌으며, 로그인 세션 유지, API 인증, 마이크로서비스 간 통신 등 웹 개발 전반에서 사실상 표준처럼 쓰이고 있습니다.
가장 큰 특징은 토큰 자체에 정보가 들어 있다는 점입니다. 서버가 세션 저장소를 따로 조회하지 않아도 토큰만 검증하면 사용자를 식별할 수 있습니다. 그리고 여기서 많은 개발자가 오해하는 부분이 나옵니다. JWT의 내용은 암호화된 것이 아니라 Base64URL 방식으로 인코딩된 것입니다. 즉 비밀 키가 없어도 누구나 디코딩해서 내용을 읽을 수 있습니다.
JWT 토큰의 3단 구조 이해하기
JWT는 마침표(.)로 구분된 세 부분으로 이루어져 있습니다. eyJ로 시작하는 긴 문자열을 본 적이 있다면 그것이 JWT일 가능성이 높습니다. eyJ는 JSON의 여는 중괄호 {\"가 Base64URL로 인코딩된 결과입니다.
| 구성 요소 | 담긴 정보 | 인코딩 여부 |
|---|---|---|
| 헤더(Header) | 서명 알고리즘(alg: HS256, RS256 등), 토큰 타입(typ) | Base64URL 인코딩, 디코딩 가능 |
| 페이로드(Payload) | 클레임(사용자 ID, 권한, 만료 시간 등 실제 데이터) | Base64URL 인코딩, 디코딩 가능 |
| 서명(Signature) | 헤더와 페이로드를 비밀 키로 서명한 값 | 키 없이는 검증 불가 |
페이로드에는 표준으로 정의된 클레임과 서비스가 자유롭게 넣는 커스텀 클레임이 함께 들어갑니다. 자주 보게 되는 표준 클레임은 다음과 같습니다.
- sub: 토큰의 주체, 보통 사용자 ID가 들어갑니다
- exp: 만료 시각, Unix 타임스탬프 초 단위입니다
- iat: 토큰 발급 시각입니다
- iss: 토큰 발급자, aud: 토큰 사용 대상입니다
JWT 토큰 디코딩 방법 3가지
1. 온라인 디코더 사용
가장 널리 알려진 방법은 jwt.io 같은 온라인 디코더입니다. 토큰을 붙여넣으면 헤더와 페이로드를 색상별로 구분해서 보여주고, 비밀 키를 입력하면 서명 검증까지 할 수 있습니다. 디코딩 처리는 브라우저 안에서 이루어지지만, 운영 환경의 실제 토큰을 외부 사이트에 붙여넣는 습관 자체가 위험할 수 있다는 점은 아래 보안 섹션에서 다시 설명하겠습니다.
2. 브라우저 콘솔에서 직접 디코딩
개발자 도구 콘솔에서 한 줄이면 충분합니다. 페이로드는 두 번째 조각이므로 이렇게 확인합니다.
JSON.parse(atob(token.split('.')[1].replace(/-/g,'+').replace(/_/g,'/')))
replace가 붙는 이유는 앞서 설명한 Base64URL과 일반 Base64의 문자 차이 때문입니다. 외부로 데이터가 나가지 않으니 실제 토큰을 다뤄야 할 때 가장 안전한 방법입니다.
3. 터미널에서 디코딩
리눅스나 맥 터미널에서는 echo 토큰의두번째조각 | base64 -d로 확인할 수 있고, jq를 함께 쓰면 JSON을 보기 좋게 출력할 수 있습니다. 서버에서 로그를 확인하다가 토큰을 바로 열어봐야 할 때 유용합니다.
디코딩 시 반드시 알아야 할 보안 주의사항
JWT 디코딩은 봉투를 열어 내용을 읽는 것이고, 서명 검증은 인감이 진짜인지 확인하는 것입니다. 누구나 봉투는 열 수 있지만 인감 확인은 키를 가진 서버만 할 수 있습니다. 이 둘을 혼동하는 순간 보안 사고가 시작됩니다.
디코딩이 쉽다는 특성 때문에 실무에서 지켜야 할 원칙이 몇 가지 있습니다.
- 페이로드에 민감 정보를 넣지 마세요. 비밀번호, 주민등록번호, 카드번호가 페이로드에 있다면 토큰을 가진 누구나 읽을 수 있습니다.
- 운영 토큰을 아무 온라인 도구에나 붙여넣지 마세요. 유효한 토큰이 외부에 노출되면 만료 전까지 그 자체로 인증 수단이 됩니다.
- 디코딩 결과만 믿고 권한을 부여하지 마세요. 서버는 반드시 서명 검증을 거친 뒤에 페이로드를 신뢰해야 합니다. 서명 검증 없이 페이로드의 role 값만 보고 관리자 권한을 주는 코드는 위조 토큰에 그대로 뚫립니다.
실무에서 바로 쓰는 활용 팁
디버깅에서 JWT 디코딩이 가장 자주 쓰이는 순간은 만료 시간 확인입니다. exp 값이 1767225600처럼 초 단위 숫자로 나오는데, 콘솔에서 new Date(exp * 1000)을 실행하면 사람이 읽을 수 있는 날짜로 바뀝니다. 401 오류가 났을 때 exp부터 확인하면 토큰 만료 문제인지 다른 문제인지 1분 안에 구분할 수 있습니다.
자주 쓰는 웹 유틸리티는 북마크 폴더 하나에 모아 두면 작업 흐름이 끊기지 않습니다. JWT 디코더 외에도 만 나이 기준이 헷갈릴 때 바로 확인하는 나이 계산기, 길게 늘어진 문서 링크를 팀 채팅에 공유할 때 쓰는 미투 단축URL 같은 도구를 함께 정리해 두면 검색하는 시간이 줄어듭니다.
오늘 해볼 일은 두 가지입니다. 지금 갖고 있는 토큰 하나를 브라우저 콘솔에서 직접 디코딩해 보고, 페이로드의 exp 값을 날짜로 변환해 보세요. 이 두 가지만 손에 익어도 인증 관련 디버깅 속도가 눈에 띄게 빨라집니다.
