JWT가 Base64URL을 쓰는 방식: 토큰 직접 디코딩하기

토큰의 구조

다음은 데모 시크릿 demo-secret-do-not-use로 서명한 완전한 HS256 토큰입니다. 읽기 쉽도록 줄을 바꿨으며, 실제 토큰은 한 줄입니다.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
.eyJzdWIiOiJ1c2VyLTQyIiwibmFtZSI6IkFkYSIsImFkbWluIjpmYWxzZSwiaWF0IjoxNzYwMDAwMDAwLCJleHAiOjE3NjAwMDM2MDB9
.nKTVXOM_r1JbE92WsFd2SSun0a1TByUV8ZpqrRUnIhk

.으로 구분된 세 부분:

헤더와 페이로드는 UTF-8로 인코딩한 JSON을 다시 Base64URL로 인코딩한 것입니다. 서명은 바이너리이므로 바이트로만 의미가 있습니다. iat와 exp는 초 단위 Unix 타임스탬프입니다. 이 토큰은 2025-10-09 08:53:20 UTC에 발급되어 한 시간 뒤에 만료되었습니다.

패딩 없는 Base64URL을 쓰는 이유

토큰은 +, /, =가 문제를 일으키는 곳을 지나다닙니다. 쿼리 문자열(+가 공백으로 바뀜), URL 경로(/는 구분자), 쿠키, HTTP 헤더가 그렇습니다. 그래서 RFC 7515에서 정의한 JWT의 서명 형식인 JWS는 RFC 4648의 URL-safe 알파벳을 쓰고 패딩을 제거합니다.

RFC 4648 5절에서 정의한 URL 및 파일 이름 안전 문자 집합을 사용하는 Base64 인코딩으로, 끝의 ‘=’ 문자를 모두 생략하며(3.2절에서 허용하는 대로) 줄 바꿈, 공백, 기타 추가 문자를 포함하지 않는다.

표준 Base64와 비교하면 두 가지가 달라집니다.

• +는 -가 되고 /는 _가 됩니다. 위의 서명에는 _가 들어 있어서 표준 디코더가 거부합니다.
• 끝에 =가 없습니다. 구간의 길이는 절대 4n+1이 아니므로, 디코더는 패딩이 얼마나 제거되었는지 항상 알아낼 수 있습니다. 길이를 4로 나눈 나머지가 2이면 ==, 3이면 =입니다.

알파벳 차이에 대한 자세한 내용은 Base64와 Base64URL 비교에 있습니다.

각 부분을 직접 디코딩하기

점으로 나누고, 표준 알파벳과 패딩을 복원하고, 디코딩한 뒤 JSON을 파싱하세요. 브라우저에서는 다음과 같습니다.

function decodePart(part) {
  const b64 = part.replace(/-/g, "+").replace(/_/g, "/");
  const padded = b64 + "=".repeat((4 - (b64.length % 4)) % 4);
  const bytes = Uint8Array.from(atob(padded), (c) => c.charCodeAt(0));
  return JSON.parse(new TextDecoder().decode(bytes));
}

const [header, payload] = token.split(".").slice(0, 2).map(decodePart);

TextDecoder 단계를 건너뛰면 ASCII가 아닌 텍스트가 깨집니다. {"name":"Zoë 日本"}이 든 페이로드는 eyJuYW1lIjoiWm_DqyDml6XmnKwifQ로 인코딩됩니다. 변환한 문자열을 atob만으로 처리하면 atob가 바이트 하나당 문자 하나를 반환하므로 이름이 Zoë로 시작하는 깨진 글자로 나옵니다. 지원하는 런타임에서는 Uint8Array.fromBase64(part, { alphabet: "base64url" })가 앞의 세 줄을 대신합니다. Uint8Array.toBase64를 참고하세요. Node.js에서는 Buffer.from(part, "base64url")이 같은 일을 합니다.

Python에서 urlsafe_b64decode는 알파벳은 처리하지만 여전히 패딩을 요구합니다.

import base64, json

def b64url_decode(s: str) -> bytes:
    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))

header, payload, signature = token.split(".")
print(json.loads(b64url_decode(header)))   # {'alg': 'HS256', 'typ': 'JWT'}
print(json.loads(b64url_decode(payload)))  # {'sub': 'user-42', 'name': 'Ada', ...}

셸에서는 tr로 알파벳을 변환하고 반복문으로 패딩을 채우세요.

jwt_part() {
  local s
  s=$(printf '%s' "$1" | tr '_-' '/+')
  while [ $(( ${#s} % 4 )) -ne 0 ]; do s="$s="; done
  printf '%s' "$s" | base64 -d
}
jwt_part "$(echo "$TOKEN" | cut -d. -f2)"

토큰 안을 들여다보기만 하면 된다면 JWT 디코더에 붙여넣으세요. 브라우저에서 실행되므로 운영 환경의 토큰이 기기 밖으로 나가지 않습니다.

페이로드를 읽을 수 있는 이유

인코딩은 암호화가 아닙니다. Base64URL은 바이트를 표기하는 방식만 바꿀 뿐이며, JWT 디코더는 키 없이도 이를 되돌립니다. 서명된 JWT는 서명 이후 페이로드가 바뀌지 않았음을 보장할 뿐, 페이로드를 숨기지는 않습니다.

인코딩은 공간도 차지합니다. 모든 클레임은 Base64URL로 인코딩되면 3분의 1만큼 커지고, 토큰 전체가 요청마다 헤더나 쿠키에 실려 다니므로 페이로드는 작게 유지하세요. 전체 사용자 프로필보다는 ID와 짧은 클레임 몇 개가 적당합니다.

모든 클레임을 공개된 것으로 취급하세요. 사용자 ID, 역할, 만료 시각은 괜찮습니다. 비밀번호, API 키, 토큰 소지자가 보면 안 되는 개인정보는 안 됩니다. 내용이 기밀이어야 한다면 암호화된 JWT(JWE)를 쓰세요. JWE의 compact 형식은 헤더, 암호화된 키, IV, 암호문, 인증 태그의 다섯 Base64URL 부분으로 이루어집니다. 일반적인 차이는 인코딩과 암호화의 차이 해설에서 다룹니다.

서명을 계산하는 방법

서명은 정확히 header.payload라는 ASCII 텍스트, 즉 두 Base64URL 문자열과 그 사이의 점을 대상으로 합니다. HS256의 경우:

import hmac, hashlib

signing_input = f"{header}.{payload}".encode("ascii")
mac = hmac.new(b"demo-secret-do-not-use", signing_input, hashlib.sha256).digest()
hmac.compare_digest(mac, b64url_decode(signature))   # True

원시 서명 바이트는 다시 패딩 없는 Base64URL로 인코딩됩니다. 길이는 알고리즘에 따라 다릅니다.

JWS의 ES256 서명은 각각 32바이트인 원시 R || S 값입니다. OpenSSL과 많은 암호 라이브러리는 대신 30으로 시작하고 길이가 가변적인 DER 인코딩 ECDSA 서명을 만듭니다. 둘 사이의 변환은 “invalid signature” 오류의 흔한 원인입니다.

HS, RS, ES, EdDSA 키로 토큰을 만들고 서명하려면 JWT 인코더를 사용하세요. Base64로 된 원시 HMAC은 HMAC 도구를 참고하세요.

흔한 실수

• atob나 표준 Base64 디코더를 그대로 사용. 우연히 -나 _가 나오느냐에 따라 어떤 토큰은 되고 어떤 토큰은 예외가 납니다. 예시의 페이로드는 atob로 디코딩되지만 서명은 그렇지 않습니다.
• 토큰을 만들 때 패딩 추가. 일부 라이브러리는 =로 끝나는 구간을 거부합니다. 제거하세요.
• 검증 전에 헤더나 페이로드를 다시 인코딩. 서명은 원래의 Base64URL 텍스트를 대상으로 합니다. JSON을 파싱해서 다시 직렬화하면 키 순서나 공백이 바뀌어 서명이 더 이상 맞지 않습니다. 항상 받은 그대로의 구간으로 검증하세요.
• 디코딩한 페이로드를 신뢰. 디코딩은 검증이 아닙니다. 기대하는 알고리즘으로 서명을 확인하고, 의도한 경우가 아니라면 "alg":"none"(헤더 eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0)을 절대 받아들이지 마세요.
• 토큰 문자열을 고유 키로 사용. 서명 32바이트에는 256비트가 필요한데 43문자는 258비트를 담습니다. 마지막 2비트는 쓰이지 않으므로, 예시에서 마지막 k를 l, m, n으로 바꿔도 관대한 디코더는 같은 바이트를 반환합니다. 서명도 여전히 검증됩니다. 보안상으로는 무해하지만 서로 다른 두 문자열이 같은 토큰을 나타낼 수 있습니다.
• 타임스탬프를 밀리초로 읽기. exp와 iat는 초 단위입니다. JavaScript의 Date에 넘기기 전에 1000을 곱하세요.

자주 묻는 질문