콘텐츠로 이동

JWT 클레임 구조 — 토큰 안에 담기는 정보

JWT(JSON Web Token)는 점(.)으로 구분된 세 부분으로 이뤄져요. 그중 가운데 페이로드(payload)가 실제로 우리가 알고 싶은 정보를 담고 있고, 그 정보 항목 하나하나를 클레임(claim)이라고 불러요. "이 토큰을 쓴 사람이 누구인지", "언제까지 유효한지" 같은 주장이 바로 클레임이에요.

개요

클레임은 토큰이 주장하는 내용을 담은 JSON 객체예요. 어떤 키가 반드시 있어야 하는지, 어떤 값을 쓰는 게 안전한지는 스펙(RFC 7519)이 표준 클레임으로 정해두고 있어요. 이를 알면 "여기에 뭘 넣고 넣지 말아야 하는지"가 분명해집니다.

핵심 개념

등록된 클레임(Registered Claims). 여러 시스템이 공통으로 이해하게끔 스펙이 이름과 의미를 정해둔 클레임이에요. 대표적으로 이렇게 있어요.

iss   발급자(누가 발급했는지)
sub   주체(누구에 대한 토큰인지)
aud   수신자(어느 API가 쓰도록 만들어졌는지)
exp   만료 시각(이 이후엔 무효)
iat   발급 시각
nbf   이 시각 이전엔 무효

exp, sub, aud는 특히 중요해요. exp(만료)를 확인하지 않으면 만료된 토큰을 계속 쓸 수 있고, aud(수신자)를 확인하지 않으면 다른 서비스용 토큰을 우리가 믿을 수 있어요. 그래서 검증 절차에서 이 클레임들을 꼭 점검하게 됩니다.

공개 클레임(Public Claims)과 비공개 클레임(Private Claims). 등록된 것 외에 사용자가 정의한 클레임은, 이름 충돌을 피하려면 공개용 레지스트리(예: IANA)에 등록하거나, 비공개로 쓰되 충돌을 피할 수 있게 애플리케이션끼리만 합의해서 써요.

페이로드는 누구나 읽을 수 있어요. base64로 인코딩되는 게 전부라서, 토큰만 있으면 내용을 디코딩해서 볼 수 있어요. 그래서 비밀번호·카드번호 같은 민감 정보는 절대 클레임으로 넣으면 안 돼요. 서명은 "내용이 위조되지 않았다"는 증거이지 "다른 사람이 못 본다"는 암호화가 아니거든요.

실제 적용(데이터스케쳐스)

로그인 후 발급하는 JWT에는 사용자 식별용 sub, 만료용 exp, 그리고 어떤 서비스에서 쓰는지 구분하는 aud를 넣는 걸 기준으로 잡아요. 서비스를 식별하는 테넌트나 역할 정보를 클레임으로 담을 때는, 그 값이 서버가 이미 알고 있는 정보와 합치되는지 설계 단계에서 확인해요.

페이로드에 민감한 데이터를 넣지 않는 게 원칙이에요. "확인이 필요하면 서버 쪽 DB를 다시 참조한다"는 설계로 가야지, 비밀 정보까지 토큰에 실어 나르면 유출 시 문제가 커져요. 어떤 클레임을 넣을지는 권한 판단(인가)의 재료가 되므로, 토큰 발급 쪽과 검증 쪽이 같은 스펙을 공유하도록 문서로 맞춰둬요.

더 알아보기