JWT 설명: 구조, 클레임, 디코딩하는 법

현대 웹 API를 다뤄 봤다면 JWT를 만난 적 있을 겁니다 — 로그인 응답과 Authorization 헤더에 나타나는, 점 두 개가 든 긴 알쏭달쏭한 문자열. 불투명해 보이지만, 구조를 알고 나면 놀랍도록 읽기 쉽습니다. 이 가이드는 JSON Web Token이 무엇인지, 그 안에 뭐가 있는지, 서명이 어떻게 동작하는지, 그리고 피해야 할 보안 실수를 설명합니다.

JWT는 무엇을 위한 것인가

JSON Web Token(JWT)은 클레임 묶음 — "이건 사용자 42이고 10:05에 로그인했다" 같은 진술 — 을 나르는 간결하고 자기완결적인 방법입니다. 주 용도는 인증입니다: 로그인하면 서버가 JWT를 발급하고, 앱은 요청마다 그것을 되보내며, 서버는 매번 세션 저장소에서 당신을 조회하는 대신 그것을 신뢰합니다. 토큰이 정보를 스스로 지니므로 무상태(stateless)라고 불립니다.

세 부분

모든 JWT는 점으로 이어진 세 개의 Base64URL 인코딩 구간입니다: header.payload.signature.

eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI0MiJ9.3x9kQ...
└──── header ────┘ └── payload ──┘ └ signature ┘

1. 헤더(Header)

토큰에 관한 메타데이터 — 서명 알고리즘(alg, 예: HS256)과 타입(typ: JWT). 디코딩하면 작은 JSON일 뿐입니다:

{ "alg": "HS256", "typ": "JWT" }

2. 페이로드(Payload)

클레임 — 실제 데이터. 일부 이름은 표준화돼 있습니다(등록된 클레임이라 부름):

• sub — 주체(subject), 보통 사용자 ID.
• iss — 발급자(issuer), 토큰을 만든 주체.
• aud — 대상(audience), 누구를 위한 것인지.
• exp — 만료 시각(Unix 타임스탬프).
• iat — 발급 시각(Unix 타임스탬프).

그 exp와 iat 값은 1970년 이후의 초입니다 — 실제 날짜로 읽어야 하면, 타임스탬프 변환기가 사람이 읽을 수 있는 시각으로 바꿔 줍니다.

3. 서명(Signature)

서명은 토큰을 신뢰할 만하게 만드는 것입니다. 발급자는 헤더와 페이로드를 가지고, 비밀 키를 써서 암호학적 서명을 만듭니다. 키를 가진 사람은 헤더와 페이로드가 변조되지 않았음을 검증할 수 있습니다 — 페이로드의 글자 하나만 바꿔도 서명이 더는 맞지 않습니다.

가장 중요하게 이해할 점

JWT는 서명된 것이지 암호화된 것이 아닙니다. 헤더와 페이로드는 Base64URL로 인코딩만 돼 있어, 누구나 디코딩해 읽을 수 있습니다 — 키가 필요 없습니다. 서명은 변조를 막지, 읽기를 막지 않습니다.

실질적 결과: JWT 페이로드에 비밀을 절대 넣지 마세요. 비밀번호도, 신용카드 번호도, 개인 데이터도 안 됩니다 — 페이로드는 공개라고 가정하세요. 우리 JWT 디코더에 아무 토큰이나 붙여 넣어 직접 확인할 수 있습니다. 헤더와 클레임을 즉시, 전부 브라우저에서 읽습니다(토큰은 기기를 떠나지 않음). 내부적으로는 그냥 Base64 디코딩이며 — 디코더는 그 단계를 대신해 줄 뿐입니다.

검증 vs. 디코딩

이 둘은 다른 행위이고, 헷갈리는 것은 진짜 보안 버그입니다. 디코딩은 페이로드를 읽습니다 — 누구나 할 수 있고 아무것도 증명하지 않습니다. 검증은 키로 서명을 확인해 토큰이 진짜이고 변조되지 않았음을 확인합니다. 서버는 신뢰하기 전에 모든 토큰을 검증해야 합니다; 디코딩만으로는 인증이 아닙니다.

흔한 함정

• 검증되지 않은 토큰을 신뢰하기 — 클레임에 따라 행동하기 전에 항상 서버 측에서 서명을 확인하세요.
• 만료 무시 — exp를 존중하세요; 만료된 토큰은 거부돼야 합니다.
• 페이로드에 민감한 데이터 저장 — 누구나 읽을 수 있습니다.
• `alg: none` 함정 — 일부 라이브러리가 한때 "서명 없음"을 주장하는 토큰을 받아들였습니다. 그것들을 거부하고, 기대하는 알고리즘을 고정하세요.

이것들을 이해하면 JWT는 위협적인 문자열에서 단순하고 투명한 포맷 — 읽을 수 있는 클레임을, 신뢰하기 전에 검증해야 하는 서명으로 보호한 것 — 이 됩니다.