JWT 구조

JWT 구조

Header, Payload, Signature로 구성되며, 각각을 "."으로 연결한 구조

Header

JSON 형식의 토큰 정보를 BASE 64로 인코딩한 값

예시

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

typ

토큰이 어떤 종류의 객체인지 식별하며 생략 가능한 헤더. 수신자가 토큰을 올바르게 처리할 수 있도록 힌트를 제공한다.

• JWT: JSON Web Token. 토큰이 JWT 표준을 따르고 있음을 나타낸다.
• JWS: JSON Web Signature. 서명된 구조의 토큰임을 나타낸다. 토큰의 무결성을 보장하며, 실무에서 대부분의 JWT는 JWS 구조를 사용한다.
• JWE: JSON Web Encryption. 암호화된 구조의 토큰임을 나타낸다. 토큰의 기밀성을 보장한다.
• JOSE: JSON Object Signing and Encryption. JWT, JWS, JWE를 포함하는 상위 프레임워크. typ 필드에 직접 사용되는 경우는 드물다.
• 기타: 필요에 따라 커스텀 토큰 타입을 정의할 수 있다.

alg

토큰을 서명하거나 암호화하는 데 사용된 알고리즘을 지정하는 필수 헤더. 이 값은 토큰의 유효성을 검증하거나 복호화하는 방법을 결정한다.

• 서명 알고리즘 (JWS): 서명 알고리즘은 토큰의 무결성을 보장하며, 토큰 내용이 위변조되지 않았음을 확인하는 데 사용된다.
  • 대칭 키: HS256/384/512. 일반적으로 가장 많이 사용됨.
  • 비대칭 키: RS256/384/512, PS256/384/512.
  • 타원 곡선 암호화: ES256/384/512.
  • 서명되지 않은 토큰: none(디버깅 목적으로만 제한적으로 사용).
• 암호화 알고리즘 (JWE): 토큰 내용을 암호화하는 키를 생성하거나 관리하는 방법을 지정한다.
  • RSA-OAEP: RSAES OAEP 암호화.
  • A128KW: AES Key Wrap (128비트 키).
  • A256KW: AES Key Wrap (256비트 키).
  • dir: Direct Encryption. 콘텐츠 암호화 키를 직접 사용.
  • ECDH-ES: 타원 곡선 Diffie-Hellman 키 합의.

Payload

JSON 형식의 사용자 인증 정보를 BASE 64로 인코딩한 값

예시

{
    "iss": "elec-dog",
    "sub": "dev-msj",
    "aud": "https://service.myblog.com"
    "exp": "1800010110438",
    "iat": "1754410115438",
    "https://elec-dog.io/rules": "USER",
    "userId": "alem",
    "isPremium": true
}

등록된 클레임(Registered Claim)

토큰에 대한 정보들을 담기 위해 미리 정해져 있는 클레임들

• iss: issuer. 토큰의 발급자.
• sub: subject. 토큰의 주체. 토큰을 사용할 사용자. ID, 이메일, 사번 등.
• aud: audience. 토큰의 대상자. 토큰을 처리할 서비스. 프론트 서버의 origin, 앱 이름, API 서비스 식별자 등
• exp: expiration. 토큰의 만료 일시. NumericDate(예: 1480849147370) 형식.
• nbf: not before. 토큰의 활성 일시. NumericDate 형식. 이 일시가 지나야 유효한 토큰이 된다.
• iat: issued at. 토큰이 발급된 일시. NumericDate 형식.
• jti: JWT의 고유 식별자. 주로 중복적인 처리를 방지하기 위하여 사용한다. 일회용 토큰에 사용한다.

공개 (public) 클레임

공식 표준화 또는 여러 조직 간 연동이 필요가 있는 토큰에 사용자 정보를 담기 위해 사용하는 클레임들

• 공개적으로 사용할 수 있도록 문서화되어 있어야 하며, 누구나 해당 클레임의 의미와 사용법을 알 수 있어야 한다.
• 이름이 고유해야 하므로, 도메인 기반의 URI를 사용해 충돌을 방지한다.
• SSO(싱글사인온), OAuth, OpenID Connect 등에서 서로 다른 회사/서비스가 JWT를 해석하기 위해 사용한다.
• 사용자 등급, 부서, 사내 권한 등 서비스마다 공통적으로 쓰는 정보를 담는다.

예시

- `https://example.com/user_id`: 특정 서비스에서 정의한 사용자 ID
- `https://mycompany.com/roles`: 회사에서 정의한 사용자 역할 정보
- `https://schemas.openid.net/claims/auth_time`: OpenID Connect에서 정의한 인증 시각

비공개 (private) 클레임

특정 서비스나 조직 내부에서만 의미를 가지는 사용자 정의 클레임

• 내부 서비스/조직 간 JWT를 주고받을 때 주로 사용한다.
• 이름 충돌 위험이 없으므로, 간단한 문자열로 자유롭게 정의할 수 있다.
• 외부 시스템과 JWT를 공유하지 않는 한, 비공개 클레임만으로 충분한 경우가 많다.

예시

- `userId`: 내부 시스템에서만 사용하는 사용자 고유 ID
- `department`: 사내에서만 사용하는 부서 정보
- `isPremium`: 프리미엄 회원 여부(내부 정책)
- `loginType`: 자체 서비스에서만 쓰는 로그인 방식 구분

Signature

토큰의 유효성을 검증하기 위한 고유의 암호화 코드

• 서명(Signature)은 토큰이 발급자에 의해 생성된다.
• 토큰의 무결성과 진위(위변조 여부)를 검증하기 위한 암호화 서명 값입니다.
• Header와 Payload의 값을 헤더(Header)에서 정의한 알고리즘과 발급자가 가진 비밀 키를 통해 검증한다.

생성 방법

1. BASE64로 인코딩된 헤더(Header)와 페이로드(Payload)의 값을 "."으로 연결한다.
2. 1의 값을 비밀 키를 이용해 헤더(Header)에서 정의한 알고리즘으로 해싱한다.
3. 2의 값을 다시 BASE64로 인코딩한다.