JWT란? — 구조와 디코딩, 보안 주의점
API를 다루다 보면 eyJhbGciOi...로 시작하는 긴 문자열을 만납니다. 로그인 응답에도, 401 오류 디버깅에도 등장하는 이것이 JWT(JSON Web Token)입니다. 구조를 한 번 이해해 두면 "토큰이 왜 안 먹히지?"를 몇 초 만에 진단할 수 있습니다.
JWT는 어디에 쓰이나
JWT는 "이 요청을 보낸 사람이 누구이고 무슨 권한이 있는지"를 담은 디지털 통행증입니다. 로그인에 성공하면 서버가 JWT를 발급하고, 이후 모든 API 요청에 Authorization: Bearer eyJ... 형태로 실어 보냅니다. 서버는 세션을 저장하는 대신 토큰의 서명만 검증하면 되어서, 모바일 앱·SPA·마이크로서비스 인증에 널리 쓰입니다.
점 두 개로 나뉘는 3부분 구조
JWT는 xxxxx.yyyyy.zzzzz처럼 점(.)으로 구분된 세 부분입니다.
| 부분 | 이름 | 담는 내용 |
|---|---|---|
| 1 | 헤더(Header) | 서명 알고리즘(HS256 등)·토큰 타입 |
| 2 | 페이로드(Payload) | 사용자 식별자(sub)·만료 시각(exp)·발급 시각(iat)·권한 등 |
| 3 | 서명(Signature) | 헤더+페이로드를 서버 비밀키로 서명한 값 |
헤더와 페이로드는 JSON을 Base64URL로 인코딩한 것입니다. 토큰이 eyJ로 시작하는 이유는 {"를 Base64로 인코딩하면 eyJ가 되기 때문입니다.
누구나 디코딩할 수 있다 — 서명의 의미
가장 중요한 사실: 헤더·페이로드는 암호화가 아니라 인코딩입니다. 토큰을 가진 사람은 누구나 내용을 볼 수 있습니다.
exp로 만료 확인 — 401 디버깅
API가 갑자기 401(인증 실패)을 반환할 때 가장 흔한 원인은 토큰 만료입니다. 토큰을 디코더에 넣어 페이로드를 확인하세요.
- exp: 만료 시각 — 유닉스 타임스탬프(초)로 기록됩니다. 현재보다 과거면 만료된 토큰입니다.
- iat: 발급 시각 — exp − iat로 토큰 수명을 알 수 있습니다.
- sub / 커스텀 클레임: 어떤 사용자·권한의 토큰인지 확인해, 엉뚱한 계정 토큰을 쓰고 있지 않은지 점검합니다.
JSON Web Token의 약자로, 로그인 상태나 권한 정보를 담아 서버와 주고받는 토큰 표준입니다. 점(.)으로 구분된 헤더·페이로드·서명 세 부분으로 이루어지며, eyJ로 시작하는 긴 문자열 형태입니다. 로그인 후 API 요청의 Authorization 헤더에 실려 '이 요청이 누구의 것인지'를 증명하는 데 널리 쓰입니다.
일반적인 JWT의 헤더와 페이로드는 암호화가 아니라 Base64URL 인코딩일 뿐이라, 토큰을 가진 사람은 누구나 내용을 볼 수 있습니다. 서명(세 번째 부분)은 내용을 숨기는 것이 아니라 위조를 막는 역할입니다. 그래서 페이로드에는 비밀번호 같은 민감 정보를 넣으면 안 되고, 토큰 자체도 비밀번호처럼 노출되지 않게 관리해야 합니다.
토큰을 디코더에 넣어 페이로드의 exp(만료 시각) 값을 확인하는 것이 가장 빠릅니다. exp는 유닉스 타임스탬프(초 단위)로 기록되며, 현재 시각보다 과거면 토큰이 만료된 것이라 재로그인이나 토큰 갱신이 필요합니다. iat(발급 시각), sub(사용자 식별자) 값도 함께 확인하면 어떤 계정의 토큰인지 파악할 수 있습니다.