| 클레임 | 설명 |
|---|---|
iss | Identifies the principal that issued the JWT. Typically the auth server URL. |
sub | Identifies the principal that is the subject of the JWT — usually the user ID. |
aud | Identifies the recipients that the JWT is intended for. The API must check this. |
exp | The time after which the JWT MUST NOT be accepted. Critical for security. |
nbf | The time before which the JWT MUST NOT be accepted. Useful for deferred activation. |
iat | The time at which the JWT was issued. Used to determine the age of the token. |
jti | Unique identifier for the JWT. Prevents token replay attacks when combined with a blocklist. |
| 클레임 | 설명 |
|---|---|
name | End-user's full name in displayable form. |
given_name | Given name(s) or first name of the end-user. |
family_name | Surname(s) or last name of the end-user. |
email | End-user's preferred email address. |
email_verified | True if the end-user's email has been verified by the Provider. |
picture | URL of the end-user's profile picture. |
locale | End-user's locale as a BCP 47 language tag. |
zoneinfo | End-user's time zone from the IANA Time Zone Database. |
updated_at | Time the end-user's information was last updated. |
nonce | String value used to associate a Client session with an ID Token and to mitigate replay attacks. |
at_hash | Hash of the Access Token value. Used to validate the access_token. |
auth_time | Time when the end-user was authenticated. |
| 클레임 | 설명 |
|---|---|
scope | OAuth 2.0 scopes granted to the token. Defines what resources the token can access. |
roles | Non-standard but widely used. Application roles assigned to the user. |
permissions | Fine-grained permissions. Used by Auth0, AWS Cognito, and others. |
azp | The client_id of the OAuth 2.0 Client that requested the token. Used with OIDC. |
acr | Level of authentication that occurred. Values defined by the deployment. |
amr | How the user was authenticated (password, OTP, biometric, etc.). |
| 클레임 | 설명 |
|---|---|
tenant_id | Multi-tenant app custom claim. Identifies the tenant/organization. |
org_id | Organization identifier used by Auth0, WorkOS, and similar platforms. |
plan | User's subscription tier. Common in SaaS billing-based access control. |
| 클레임 | 설명 |
|---|---|
Verify exp | Reject any token where exp < current time (in UTC seconds). Add small clock skew (30–60s). |
Verify iss | Must exactly match the expected issuer URL. Reject mismatches. |
Verify aud | Must contain your API's identifier. Reject tokens issued for other audiences. |
Verify signature | NEVER trust a JWT without verifying its cryptographic signature using the correct key/JWKS. |
Check nbf | If nbf is present, reject tokens used before this time. |
Check alg | Explicitly specify expected algorithm. Reject 'none' algorithm. Prefer RS256 or ES256 over HS256 for public APIs. |
| 클레임 | 설명 |
|---|---|
HS256 | Fast; uses a single shared secret for sign & verify. Only suitable when both parties are trusted (e.g., server-to-server). |
HS512 | Like HS256 but with 512-bit hash output. Marginally stronger for symmetric use cases. |
RS256 | Most widely supported asymmetric algorithm. Sign with private key, verify with public key. Use this for public APIs and OIDC. |
RS512 | RS256 with SHA-512. Stronger hash but same RSA security level. Marginally slower. |
ES256 | Compact, fast asymmetric algorithm. Smaller keys than RSA for equivalent security. Recommended for new systems. |
PS256 | More secure padding than RS256 (probabilistic). Required by FAPI (Financial-grade API) and advanced OIDC profiles. |
EdDSA | Modern elliptic curve algorithm. Fastest, smallest signatures. Use with jose library. Not universally supported yet. |
JWT는 점으로 구분된 세 개의 Base64URL 인코딩 부분으로 구성됩니다: 헤더.페이로드.서명
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJzdWIiOiJ1c2VyXzEyMyIsImF1ZCI6Imh0dHBzOi8vYXBpLmV4YW1wbGUuY29tIiwiZXhwIjoxNzM1Njg5NjAwLCJpYXQiOjE3MzU2MDMyMDAsInNjb3BlIjoicmVhZDp1c2VycyJ9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
{"alg":"RS256","typ":"JWT"}알고리즘과 토큰 유형
{"iss":"https://auth.example.com","sub":"user_123","exp":1735689600,...}클레임 — 데이터
RSASHA256(base64url(header) + '.' + base64url(payload), privateKey)암호화 검증
exp (만료 시간)는 토큰이 만료되는 시간으로 이 시간 이후에는 수락되어서는 안 됩니다. nbf (유효 시작 시간)는 토큰이 유효해지는 시간으로 이 시간 이전에는 수락되어서는 안 됩니다. iat (발급 시간)는 토큰이 발급된 시간을 기록하여 토큰 사용 기간을 판단하는 데 유용합니다. 세 가지 모두 NumericDate 형식(Unix epoch 이후 초)을 사용합니다.
액세스 토큰은 단기여야 합니다: 대부분의 앱에서 5-60분, API에서 1-24시간. 리프레시 토큰은 더 길 수 있습니다: 수일에서 수주. 짧은 만료 시간은 토큰 도난으로 인한 피해를 최소화합니다. JWT 페이로드는 base64url 인코딩(암호화되지 않음)이므로 누구나 디코딩할 수 있어 민감한 데이터를 저장하지 마세요.
sub (주체)는 JWT가 나타내는 주체(일반적으로 사용자 ID)를 식별합니다. 발급자의 컨텍스트 내에서 고유해야 합니다. 변경될 수 있는 사용자 이름이나 이메일보다는 안정적이고 재할당 불가능한 식별자(UUID 또는 숫자 ID 등)를 사용하세요.
네, 상태 없는 인증을 위해서는 그렇습니다. 커스텀 클레임에 역할/권한을 포함하세요(예: 'roles': ['admin', 'user']). 그러나 토큰을 가볍게 유지하세요 — 모든 것을 포함하지 마세요. 세밀한 권한의 경우 JWT에 세션 ID를 포함하고 서버 측에서 권한을 조회하는 참조 토큰 패턴을 고려하세요.