JWT란 무엇인가?

인증을 다루는 최신 웹 애플리케이션을 만들어 본 적이 있다면 거의 확실히 JSON Web Token, 흔히 JWT(“조트”라고 읽습니다)라고 줄여 부르는 것을 다뤄 보았을 것입니다. JWT는 두 당사자 사이에서 클레임(claim)의 집합을 나타내는, 간결하고 URL에 안전한 방식입니다. RFC 7519에 정의되어 있으며 REST API의 무상태(stateless) 인증에서 사실상의 표준이 되었습니다.

JWT(JSON Web Token) 이해하기: 구조·클레임·안전한 디버깅

핵심은 무상태라는 말입니다. 서버가 세션 데이터를 메모리나 데이터베이스에 저장하는 전통적인 세션 기반 인증과 달리, JWT는 필요한 정보를 모두 토큰 자체에 담고 있습니다. 서버는 아무것도 조회할 필요 없이 서명을 검증하고 내용을 신뢰하기만 하면 됩니다.

가공되지 않은 JWT는 다음과 같이 생겼습니다.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyXzEyMyIsInJvbGUiOiJhZG1pbiIsImV4cCI6MTczNjkwMDgwMH0.Xe4kJl7YQoLPkZ3r9Vv2mHgGqNtWbF8sDcA1eRfuByk

점으로 구분된 Base64Url 인코딩 세그먼트 세 개입니다. 각 세그먼트에는 정해진 역할이 있습니다.


세 부분의 구조

1. 헤더(Header)

헤더는 토큰 자체를 설명하는 JSON 객체로, 주로 어떤 알고리즘으로 서명했는지를 담습니다.

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

alg는 서명 알고리즘을 나타냅니다. 흔한 값은 다음과 같습니다.

알고리즘 종류 비고
HS256 대칭(HMAC-SHA256) 서명과 검증에 같은 공유 비밀 하나를 사용
RS256 비대칭(RSA-SHA256) 개인 키로 서명하고 공개 키로 검증
ES256 비대칭(ECDSA-SHA256) RSA보다 작은 키, 점점 인기를 얻는 중
none 서명 없음 위험: 운영 환경에서는 절대 받아들이지 마세요

2. 페이로드(Payload)

페이로드에는 실제 데이터가 들어 있습니다. 각 데이터를 클레임(claim) 이라고 부릅니다.

{
  "sub": "user_123",
  "name": "Alex Chen",
  "role": "admin",
  "iat": 1736814400,
  "exp": 1736900800
}

클레임은 세 가지로 나뉩니다.

등록된 클레임(RFC 7519에서 표준화):

  • iss(Issuer): 토큰을 발급한 주체. 예: "https://auth.example.com"
  • sub(Subject): 토큰이 가리키는 주체. 보통 사용자 ID
  • aud(Audience): 토큰의 수신 대상
  • exp(Expiration Time): 이 Unix 타임스탬프 이후에는 토큰을 거부해야 함
  • iat(Issued At): 토큰이 만들어진 Unix 타임스탬프
  • nbf(Not Before): 이 Unix 타임스탬프 이전에는 토큰을 받아들이면 안 됨

공개 클레임: IANA JWT 클레임 레지스트리에 정의되거나 충돌을 피하기 위해 URI 네임스페이스를 사용합니다.

비공개 클레임: 위 예의 role이나 plan처럼 당사자끼리 합의한 사용자 정의 클레임입니다.

중요한 주의: 페이로드는 인코딩되어 있을 뿐 암호화되어 있지 않습니다. 토큰을 가진 사람이면 누구나 Base64 디코딩으로 페이로드를 읽을 수 있습니다. 비밀번호, 신용카드 번호 등 민감한 데이터를 JWT 페이로드에 절대 넣지 마세요.

3. 서명(Signature)

서명은 다음과 같이 계산합니다(HS256을 예로).

HMAC-SHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secretKey
)

서명 덕분에 JWT는 변조를 알아챌 수 있습니다. 헤더나 페이로드의 한 글자만 바꿔도 서명이 더 이상 맞지 않아 토큰이 거부됩니다. 서버는 토큰을 어디에도 저장할 필요 없이, 기대되는 서명을 다시 계산해 제공된 서명과 비교하기만 하면 됩니다.


실제 JWT 인증은 어떻게 동작하나

일반적인 흐름은 다음과 같습니다.

  1. 로그인: 사용자가 자격 증명(사용자 이름과 비밀번호)을 인증 엔드포인트에 보냅니다.
  2. 토큰 발급: 서버가 자격 증명을 검증하고, 비밀 또는 개인 키로 서명한 JWT를 만들어 클라이언트에 돌려줍니다.
  3. 이후 요청: 클라이언트가 Authorization 헤더에 JWT를 담습니다: Authorization: Bearer <token>.
  4. 검증: 서버가 서명을 검증하고 exp를 확인한 뒤 클레임을 읽습니다. 이 모든 과정에 데이터베이스 조회가 필요 없습니다.
// 서버 측 검증 예시(Node.js, jose 라이브러리 사용)
import * as jose from 'jose';

async function verifyRequest(authHeader) {
  const token = authHeader?.split(' ')[1];
  if (!token) throw new Error('No token provided');

  const secret = new TextEncoder().encode(process.env.JWT_SECRET);
  const { payload } = await jose.jwtVerify(token, secret, {
    issuer: 'https://auth.example.com',
    audience: 'https://api.example.com',
  });

  return payload; // { sub, role, exp, ... }
}

JWT와 세션 토큰의 차이

두 방식 모두 유효합니다. 어느 쪽이 맞는지는 아키텍처에 달려 있습니다.

관점 JWT(무상태) 세션 토큰(상태 유지)
서버 저장소 필요 없음 세션 저장소(Redis, DB)
폐기 어려움: 만료를 기다리거나 차단 목록을 유지해야 함 쉬움: 저장소에서 삭제
수평 확장 자연스러움: 어느 서버든 검증 가능 공유 세션 저장소가 필요
토큰 크기 큼(클레임을 담음) 작음(ID뿐)
적합한 용도 마이크로서비스, API, 모바일 전통적인 웹 앱

흔한 보안 함정

alg: none 공격

초기 JWT 라이브러리 중에는 alg: none, 즉 서명이 필요 없는 상태를 허용하는 것이 있었습니다. 공격자는 서명을 떼어 내고 임의의 페이로드를 만들 수 있었습니다. 서버가 받아들이는 알고리즘을 항상 명시적으로 지정하고 none은 거부하세요.

// jose: 기본적으로 안전합니다. 키를 반드시 제공해야 하며 서명 없는 토큰은 거부합니다
await jose.jwtVerify(token, secret); // alg가 "none"이면 예외가 발생합니다

알고리즘 혼동(RS256 → HS256)

서버가 RS256(비대칭)을 기대하는데 공격자가 헤더를 HS256(대칭)으로 바꾸면, 일부 라이브러리는 공개 키를 HMAC 비밀로 사용합니다. 공개 키는 말 그대로 공개되어 있으므로 공격자는 유효한 토큰을 위조할 수 있습니다. 해결책: 서버 측에서 허용하는 알고리즘을 고정하세요.

JWT를 localStorage에 저장하기

localStorage에 저장된 토큰은 페이지의 모든 JavaScript가 접근할 수 있어 XSS 공격에 취약합니다. JavaScript가 접근할 수 없는 HttpOnly 쿠키를 권장합니다.

갱신 없이 수명이 긴 토큰

exp를 일주일이나 한 달로 정하고 싶어지지만, 그러면 탈취된 토큰이 오랫동안 유효합니다. 수명이 짧은 액세스 토큰(15~60분)과 안전하게 보관한 수명이 긴 리프레시 토큰을 함께 쓰세요.


JWT를 수동으로 디코딩하는 방법

페이로드는 그저 Base64Url로 인코딩되어 있으므로 라이브러리 없이도 디코딩할 수 있습니다.

function decodeJWT(token) {
  const parts = token.split('.');
  if (parts.length !== 3) return null;

  // Base64Url → Base64 → 디코딩
  const decode = (str) =>
    JSON.parse(atob(str.replace(/-/g, '+').replace(/_/g, '/')));

  return {
    header:  decode(parts[0]),
    payload: decode(parts[1]),
    // 참고: 서명(parts[2])은 비밀이나 공개 키 없이는 검증할 수 없습니다
  };
}

const { header, payload } = decodeJWT('eyJhbGci...');
console.log(payload.exp); // 1736900800

디버깅에는 이것으로 충분합니다. 하지만 기억하세요. 디코딩은 검증과 다릅니다. 어떤 클레임이든 신뢰하기 전에 항상 서버에서 서명을 검증하세요.


브라우저에서 안전하게 디버깅하기

운영 환경의 토큰을 디버깅할 때는 딜레마가 생깁니다. 안을 봐야 하지만 실제 사용자의 JWT를 제3자 온라인 도구에 붙여넣는 것은 보안 위험입니다. 그 토큰에는 사용자 ID, 역할, 그 밖의 민감한 메타데이터가 들어 있을 수 있습니다.

DevToolKits의 JWT 도구는 토큰을 전적으로 브라우저 안에서 처리합니다. 서버로는 아무것도 전송되지 않으며, 브라우저의 네트워크 탭을 열고 토큰을 붙여넣어 보면 나가는 요청이 하나도 없다는 것을 직접 확인할 수 있습니다. 비밀이나 공개 키를 넣어 클라이언트 측에서 서명을 검증할 수도 있습니다.


클레임 점검(경고)

JWT 디버거는 서명 검증과는 별도로, 디코딩한 페이로드의 클레임을 점검해 경고를 표시합니다. 서명이 올바르더라도 다음과 같은 토큰은 운영에서 문제가 됩니다.

경고 찾는 조건
exp가 없음 만료되지 않는 토큰
유효 기간이 김 exp − iat가 24시간을 넘음(예: 1d 1h)
iat가 미래 현재 시각보다 60초를 넘게 앞섬(시계 오차는 허용)
nbf가 exp보다 뒤 유효해지기 전에 만료됨
시각이 밀리초 exp·iat·nbf가 10^11을 넘음(JWT의 시각은 초 단위)
iss가 기대값과 다름 ‘기대하는 발급자’를 입력했을 때
aud에 기대값이 없음 ‘기대하는 수신자’를 입력했을 때(aud는 문자열이든 배열이든 하나라도 일치하면 통과)

iss와 aud는 기대값을 입력했을 때만 점검합니다. API 쪽 검증이 iss·aud를 반드시 확인하는 설계인지 확인하거나, 환경별 설정 실수(운영의 aud를 스테이징에 쓰는 등)를 찾을 때 쓸 수 있습니다.

2026년 11월에 추가된 기능

  • 테스트용 키 쌍(ES256, RS256, PS256, ES384, EdDSA)을 만들 수 있습니다. 개인 키는 PKCS#8 PEM과 JWK, 공개 키는 SPKI PEM과 JWK로 나오며 «위의 서명에 사용»으로 서명 양식에 넣을 수 있습니다.
  • 개인 키 JWK로도 서명할 수 있습니다. 키는 브라우저 안에서 만들어지며 전송되지 않습니다. 테스트 전용이며 운영 환경에서는 쓰지 마세요.

도구에서 직접 해 보기

자주 묻는 질문

JWT의 최대 크기는 어느 정도인가요?

JWT 사양에는 엄격한 크기 제한이 없지만 현실적인 제약이 있습니다. HTTP 헤더에는 한계가 있고(보통 헤더당 8KB) 브라우저는 쿠키 크기를 제한합니다(약 4KB). 페이로드를 가볍게 유지하세요. 받는 쪽에서 실제로 읽어야 하는 클레임만 넣습니다.

만료 전에 JWT를 무효화할 수 있나요?

기본적으로는 안 됩니다. 무상태 토큰의 트레이드오프 중 하나입니다. 흔한 대안은 (1) 폐기된 토큰 ID(jti 클레임에 저장)의 차단 목록을 서버에 유지하기, (2) 만료 시간을 매우 짧게 두기, (3) 서명 키를 교체하고 이전 키는 짧은 허용 기간만 인정하기입니다.

JWT 암호화(JWE)는 JWT 서명(JWS)과 다른가요?

다릅니다. 일반적인 JWT는 JWS(JSON Web Signature)로, 페이로드는 읽을 수 있지만 변조를 알아챌 수 있습니다. JWE(JSON Web Encryption)는 페이로드를 암호화해 복호화 키 없이는 내용을 읽을 수 없게 합니다. JWS가 훨씬 흔하며, JWE는 페이로드 자체에 전송 중에 보여서는 안 되는 데이터가 있을 때만 쓰세요.

JWT 비밀을 모든 서비스에서 같게 써도 되나요?

안 됩니다. 서비스별 또는 토큰 종류별(액세스 토큰과 리프레시 토큰)로 서명 키를 분리하세요. 한 키가 유출되었을 때의 피해 범위를 좁히고 키 교체도 쉬워집니다.

토큰 갱신은 어떻게 다루나요?

수명이 짧은 액세스 토큰(예: 15분)과 HttpOnly 쿠키에 보관하는 수명이 긴 리프레시 토큰(예: 7일)을 발급합니다. 액세스 토큰이 만료되면 클라이언트가 리프레시 토큰을 전용 엔드포인트로 보내 새 액세스 토큰을 발급받습니다. 리프레시 토큰은 사용할 때마다 교체(무효화 후 재발급)해야 합니다.