JWT 디코더 & 디버거
JWT 토큰 디코딩, 검사, 검증 — 빠르고 안전하며 서버 전송 없음.
▼ Header
▼ Payload
▶ Signature
JWT란 무엇인가?
JSON Web Token(JWT)은 RFC 7519에 정의된 간결하고 URL에 안전한 토큰 형식입니다. JWT는 웹 애플리케이션, API, 마이크로서비스에서 인증과 인가에 널리 사용됩니다. 웹사이트에 로그인하면 서버가 JWT를 발급하고, 브라우저가 이후 모든 요청에 이 토큰을 보내 신원을 증명합니다.
전통적인 세션 기반 인증과 달리 JWT는 자기 완결적입니다 — 토큰을 검증하는 데 필요한 모든 정보가 토큰 자체에 인코딩되어 있습니다. 이로 인해 무상태 아키텍처와 분산 시스템에 이상적입니다.
JWT 구조 (Header, Payload, Signature)
JWT는 점(.)으로 구분된 세 부분으로 구성됩니다:
- Header — 토큰 타입(
typ: JWT)과 서명 알고리즘(alg: HS256, RS256 등)을 포함합니다. - Payload — 클레임(사용자 정보와 메타데이터)을 포함합니다.
exp(만료),iss(발급자),sub(주체) 등 등록 클레임과 커스텀 데이터가 있습니다. - Signature — 인코딩된 Header와 Payload를 비밀키(HS256) 또는 개인키(RS256/ES256)로 서명하여 생성합니다. 서명은 토큰이 변조되지 않았음을 보장합니다.
각 부분은 Base64URL로 인코딩되어 URL에 안전하고 HTTP 헤더, 쿠키, URL 파라미터로 전송할 수 있을 만큼 간결합니다.
주요 JWT 클레임
JWT 사양은 7개의 등록 클레임을 정의합니다:
| 클레임 | 이름 | 설명 |
|---|---|---|
| iss | 발급자 | 토큰을 발행한 주체 |
| sub | 주체 | 토큰의 대상 (보통 사용자 ID) |
| aud | 수신자 | 토큰의 의도된 수신자 |
| exp | 만료 시간 | 토큰이 만료되는 Unix 타임스탬프 |
| nbf | 유효 시작 | 이 시간 전에는 토큰 무효 |
| iat | 발급 시간 | 토큰이 생성된 시점 |
| jti | JWT ID | 토큰의 고유 식별자 |
JWT vs 세션/쿠키
인증 시스템을 구축할 때 JWT 기반과 세션 기반 중 어떤 방식을 선택할지 결정해야 합니다. 각 방식은 아키텍처에 따라 서로 다른 장단점이 있습니다:
| 항목 | JWT | 세션/쿠키 |
|---|---|---|
| 상태 관리 | Stateless — 토큰에 모든 정보 포함 | Stateful — 서버에 세션 데이터 저장 |
| 확장성 | 수평 확장 용이 (공유 스토어 불필요) | 공유 세션 스토어 필요 (Redis, DB) |
| 크기 | 토큰이 클 수 있음 (모든 클레임 포함) | 쿠키는 작음 (세션 ID만) |
| 무효화 | 어려움 (블랙리스트 또는 짧은 만료 필요) | 쉬움 (서버에서 삭제) |
| 보안 위험 | 토큰 탈취 (localStorage 저장 시 XSS) | CSRF 공격 (SameSite 쿠키로 완화) |
| 적합한 환경 | API, 마이크로서비스, 모바일, SSO | 전통적 웹앱, 서버 렌더링 페이지 |
어느 방식이 절대적으로 좋다고 할 수 없습니다. JWT는 여러 서비스가 중앙 세션 스토어 없이 신원을 검증해야 하는 분산/무상태 아키텍처에 적합합니다. 세션은 즉시 무효화가 중요한 전통적 서버 렌더링 애플리케이션에서 더 간단하고 안전합니다.
자주 발생하는 JWT 오류와 해결 방법
JWT를 사용하면서 자주 마주치는 에러 메시지들입니다. 위 도구에 토큰을 붙여넣어 Header와 Payload를 확인하면 디버깅에 도움이 됩니다.
TokenExpiredError: jwt expired
원인: exp 클레임의 타임스탬프가 지났습니다. 토큰이 더 이상 유효하지 않습니다.
해결: 인증 서버에서 새 토큰을 발급받으세요. 서버를 관리하고 있다면 토큰 수명을 연장하거나 리프레시 토큰 흐름을 구현하는 것을 고려하세요. 이 도구로 정확한 만료 시간을 확인할 수 있습니다.
JsonWebTokenError: jwt malformed
원인: 토큰 문자열이 유효한 JWT 형식이 아닙니다. 토큰이 잘려있거나, 손상되었거나, Base64URL 인코딩이 올바르지 않은 경우입니다.
해결: 완전한 토큰 문자열을 복사했는지 확인하세요. 추가 공백이나 줄바꿈이 없는지 확인하고, 세 파트를 구분하는 점(.)에 URL 인코딩이 적용되지 않았는지 확인하세요.
JsonWebTokenError: invalid signature
원인: 서명이 Header와 Payload와 일치하지 않습니다. 토큰이 변조되었거나 예상과 다른 키로 서명되었습니다.
해결: 서버가 올바른 서명 키를 사용하고 있는지 확인하세요. 최근 키를 교체했다면 검증 측에 업데이트된 공개키가 있는지 확인하세요. 위의 서명 검증 기능으로 키를 테스트할 수 있습니다.
Error: JWT must have 3 parts
원인: 입력에 점으로 구분된 3개 세그먼트(header.payload.signature)가 정확히 포함되어 있지 않습니다.
해결: 완전한 JWT 토큰을 붙여넣고 있는지 확인하세요. 유효한 JWT는 항상 정확히 2개의 점을 가집니다. 토큰이 Bearer 로 시작하면 그 접두사를 제거한 후 붙여넣으세요.
JWT 보안 모범사례
- 항상 만료 시간(
exp)을 설정하세요 — 만료가 없는 토큰은 영원히 유효합니다. alg: "none"을 절대 사용하지 마세요 — 서명 검증이 비활성화되어 누구나 토큰을 위조할 수 있습니다.- Payload에 민감한 데이터를 저장하지 마세요 — JWT는 인코딩되었을 뿐 암호화되지 않습니다.
- 강력한 서명 알고리즘을 사용하세요 — 프로덕션에서는 HS256보다 RS256이나 ES256을 권장합니다.
- 토큰 수명을 짧게 유지하세요 — 장기 세션에는 리프레시 토큰을 사용하세요.
iss와aud클레임을 검증하세요 — 토큰이 올바른 발급자로부터 왔고 올바른 대상을 위한 것인지 확인하세요.
사용 방법
- 위 입력창에 JWT 토큰을 붙여넣거나, 샘플 입력을 클릭하여 데모 토큰을 시도하세요.
- 도구가 즉시 Header와 Payload를 구문 하이라이팅하여 디코딩합니다.
- 시간 기반 클레임(
exp,iat,nbf)이 선택한 타임존의 읽을 수 있는 날짜로 자동 변환됩니다. - 보안 문제가 감지되면 경고가 표시됩니다 (예:
alg: none, 만료 미설정, 민감 데이터). - → JSON 포맷터를 클릭하면 디코딩된 Payload를 JSON Formatter 도구에서 자세히 확인할 수 있습니다.
- 선택적으로 비밀키를 입력하고 서명 검증을 클릭하여 서명의 유효성을 확인할 수 있습니다.
개인정보 보호
JWT 토큰은 JavaScript를 사용하여 브라우저에서 완전히 처리됩니다. 어떤 서버로도 전송되지 않습니다. 모든 디코딩, 클레임 분석, 보안 검사, 서명 검증이 로컬에서 이루어집니다. 브라우저 개발자 도구의 네트워크 탭을 열어 토큰 데이터로 요청이 전송되지 않는 것을 직접 확인할 수 있습니다. 이 도구는 프로덕션 토큰과 민감한 자격 증명에 안전하게 사용할 수 있습니다.