108 lines
9.0 KiB
Markdown
108 lines
9.0 KiB
Markdown
---
|
|
title: RFC 7519 — JSON Web Token (JWT) Claim Validation
|
|
source_type: official-doc
|
|
url: https://datatracker.ietf.org/doc/html/rfc7519
|
|
archive_url:
|
|
status: raw
|
|
confidence: high
|
|
related_branches: [feature-security-operational-baseline, feature-management-actuator-security-contract, feature-keycloak-oauth2-proxy-oidc-flow, feature-keycloak-nginx-auth-request-integration]
|
|
related_projects: [ca-skeleton, keycloak-patterns]
|
|
tags: [ca-security, jwt, oauth2, resource-server, clock-skew, ietf-rfc, official-doc]
|
|
created: 2026-05-22
|
|
last_reviewed: 2026-05-27
|
|
---
|
|
|
|
# RFC 7519 — JSON Web Token (JWT) Claim Validation
|
|
|
|
> Layer: `raw/official-docs/` — IETF Standards Track RFC. JWT claim 검증의 사실상 표준 base 규격. `ca-skeleton` 의 Security Operational Baseline (Group G-B) 의 JWT Resource Server 경로 정당화 근거.
|
|
|
|
## Parent / 활용 branch (필수)
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-security-operational-baseline]] | clock skew 60s / `aud` mismatch → 401 / `iss` mismatch 처리 정책의 RFC 직접 매핑 근거 |
|
|
| [[raw/branch-notes/feature-management-actuator-security-contract]] | actuator/management endpoint 의 JWT 검증 경로 결정 (mTLS 대안과의 비교 기준선) |
|
|
| [[raw/branch-notes/feature-keycloak-oauth2-proxy-oidc-flow]] | Keycloak ID token 의 `aud`/`iss`/`exp` claim 검증 시 RFC 7519 spec 준수 근거 |
|
|
| [[raw/branch-notes/feature-keycloak-nginx-auth-request-integration]] | nginx auth_request 흐름의 backend JWT 검증 단계 spec 근거 |
|
|
|
|
## 컨텍스트 / 왜 저장했는지
|
|
|
|
`feature-security-operational-baseline` ca-tmpl 이 결정한 `clock skew 60s`, `issuer mismatch`, `audience mismatch`, `expired token` 분류는 RFC 7519 의 `exp`/`nbf`/`aud`/`iss` claim 처리 규정과 직접 매핑됩니다. baseline 이 RFC 표준의 권고를 어떻게 구체화했는지 확인하기 위한 1차 근거.
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://datatracker.ietf.org/doc/html/rfc7519
|
|
- 아카이브 URL: (미수집)
|
|
- 저자 / 조직: IETF — M. Jones (Microsoft), J. Bradley (Ping), N. Sakimura (NRI)
|
|
- 발행일: May 2015 (Standards Track)
|
|
- 마지막 확인일: 2026-05-27
|
|
- 관련 표준: RFC 7515 (JWS), RFC 7517 (JWK / JWKS), RFC 7518 (JWA)
|
|
|
|
## 핵심 인용 / Key quotes (verbatim)
|
|
|
|
> [§4.1.1 `iss` claim] "The processing of this claim is generally application specific."
|
|
|
|
> [§4.1.3 `aud` claim] "If the principal processing the claim does not identify itself with a value in the 'aud' claim when this claim is present, then the JWT MUST be rejected."
|
|
|
|
> [§4.1.4 `exp` claim] "The JWT MUST NOT be accepted for processing" (on or after expiration time). "Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew."
|
|
|
|
> [§4.1.5 `nbf` claim] "The JWT MUST NOT be accepted for processing" (before the not-before date/time). "Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew."
|
|
|
|
> [§4.1.6 `iat` claim] "The 'iat' (issued at) claim identifies the time at which the JWT was issued."
|
|
|
|
> [§4.1.7 `jti` claim] "The 'jti' claim can be used to prevent the JWT from being replayed."
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| JWT-RFC7519-C1 | `aud` claim 이 존재할 때, principal 이 자신을 `aud` 값에 식별시키지 못하면 JWT 는 **MUST be rejected** | [§4.1.3] "If the principal processing the claim does not identify itself with a value in the 'aud' claim when this claim is present, then the JWT MUST be rejected." | `official-standard` | `aud` claim 이 포함된 JWT 처리 | `aud` 가 누락된 token 의 거절 의무 (`MAY` 영역으로 별도 §4.1.3 후속 문장 — 본 인용 범위 밖) |
|
|
| JWT-RFC7519-C2 | `exp` 시각 도달 이후 JWT 는 **MUST NOT be accepted**, 단 "usually no more than a few minutes" 범위의 clock skew leeway 는 implementer 가 **MAY** 허용 | [§4.1.4] "The JWT MUST NOT be accepted for processing" + "Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew." | `official-standard` | `exp` claim 검증 시 | "60s" 등 구체 leeway 값을 RFC 가 강제한다는 뜻은 아님 — implementer 재량 (단 "a few minutes" 상한) |
|
|
| JWT-RFC7519-C3 | `nbf` 시각 이전 JWT 는 **MUST NOT be accepted**, 동일하게 clock skew leeway **MAY** | [§4.1.5] "The JWT MUST NOT be accepted for processing" + "Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew." | `official-standard` | `nbf` claim 검증 시 | `nbf` claim 부재 시 동작 (RFC 는 claim 자체가 optional) |
|
|
| JWT-RFC7519-C4 | `iss` claim 의 처리는 일반적으로 **application specific** — RFC 는 검증 정책을 강제하지 않음 | [§4.1.1] "The processing of this claim is generally application specific." | `official-standard` | `iss` claim 운영 정책 결정 시 | issuer mismatch 시 401 응답이 표준이라는 뜻이 아님 — 응답 결정은 application 정책 |
|
|
| JWT-RFC7519-C5 | `jti` claim 은 JWT 의 replay 방지에 사용 가능 — RFC 명시 | [§4.1.7] "The 'jti' claim can be used to prevent the JWT from being replayed." | `official-standard` | replay 방어 메커니즘 설계 시 | 모든 JWT 가 `jti` 를 포함해야 한다는 뜻은 아님 — claim 자체는 optional |
|
|
| JWT-RFC7519-C6 | `iat` claim 은 JWT 가 발행된 시각을 식별 | [§4.1.6] "The 'iat' (issued at) claim identifies the time at which the JWT was issued." | `official-standard` | token freshness 검증 / audit logging | `iat` 가 만료 계산의 base 라는 뜻 아님 — `exp` 가 독립적으로 명시됨 |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- **이 자료가 직접 증명하는 것**:
|
|
- `JWT-RFC7519-C1`: `aud` mismatch 거절은 RFC **강제** (MUST). ca-tmpl `AUTH_AUDIENCE_MISMATCH` → 401 의 변경 여지 없는 부분.
|
|
- `JWT-RFC7519-C2` / `C3`: clock skew leeway 의 정량 상한 ("a few minutes"). ca-tmpl 60s 가 "보수적" 이라는 평가의 근거.
|
|
- `JWT-RFC7519-C4`: `iss` 처리 정책이 application 재량이라는 사실 (ca-tmpl 의 `AUTH_ISSUER_MISMATCH` → 401 결정이 RFC 위반 아님).
|
|
- **이 자료가 증명하지 않는 것**:
|
|
- signature 검증 자체의 절차 (RFC 7515 / JWS 위임).
|
|
- `kid` parameter / JWKS rotation 정책 (RFC 7517 / JWK 영역).
|
|
- JWT revocation / logout 메커니즘 — JWT 는 stateless 이므로 RFC 범위 밖.
|
|
- 401 vs 403 의 HTTP semantics 선택 — RFC 7235 / HTTP 표준 위임.
|
|
- Spring Security 의 `JwtTimestampValidator` 기본값이 60s 라는 사실 — **Spring 벤더 문서로 별도 확인 필요** (RFC 는 구체 값 미지정).
|
|
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
|
|
- ca-tmpl `clock skew = 60s` 가 실제 운영 환경(NTP drift) 에서 충분한지의 실증.
|
|
- 다중 audience (multi-`aud`) JWT 처리 시 어떤 값을 식별 기준으로 할지 — RFC 가 단일/복수 모두 허용.
|
|
- `iss` whitelist 운영 시 Keycloak realm endpoint 의 `iss` claim 값 정확도 (별도 OIDC discovery doc 확인).
|
|
|
|
## 메모 / Notes (내 프로젝트 해석)
|
|
|
|
> 본 섹션은 자료 직접 인용 아님. ca-tmpl baseline 해석.
|
|
|
|
- **clock skew 정책 근거**: RFC 가 "a few minutes" 정도의 leeway 를 허용. ca-tmpl 60s 는 RFC 권고 ("usually no more than a few minutes") 안에 들어가는 보수적 값. Spring Security `JwtTimestampValidator` 의 기본 leeway 는 60초 (별도 Spring 벤더 doc 확인 필요).
|
|
- **aud mismatch 는 MUST reject**: ca-tmpl 의 `AUTH_AUDIENCE_MISMATCH` → 401 은 RFC 4.1.3 의 강제 거절 규정 그대로 구체화한 것. 변경 여지 없음.
|
|
- **iss mismatch 는 application 정책**: RFC 는 처리를 명시하지 않음. ca-tmpl 이 `AUTH_ISSUER_MISMATCH` → 401 로 정한 것은 합리적 구체화이며 RFC 위반 아님.
|
|
- **kid handling 은 RFC 7519 자체엔 없음**: RFC 7517(JWK) 의 `kid` parameter + JWS Header `kid` 사용. ca-tmpl 의 unknown `kid` + JWKS refresh 정책은 RFC 7517/7515 의 영역.
|
|
- **장점 (baseline 채택 이유)**:
|
|
- 모든 OIDC/OAuth2 Resource Server 구현이 따르는 표준.
|
|
- claim 검증 항목이 명확히 열거되어 있어 baseline matrix 12행과 mapping 가능.
|
|
- **단점 / 한계**:
|
|
- revocation 은 RFC 범위 밖. JWT 자체는 stateless 이므로 logout/revocation 은 별도 메커니즘 필요 → ca-tmpl scope 밖이지만 운영자가 알아야 함.
|
|
- signature 검증 자체 절차는 RFC 7515(JWS) 위임.
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 official-doc:
|
|
- [[raw/official-docs/security-oauth2-pkce-rfc-8252]] (OAuth2 native app PKCE)
|
|
- [[raw/official-docs/oauth2-pkce-rfc-7636]] (PKCE proof key)
|
|
- [[raw/official-docs/security-mtls-rfc-8705]] (mTLS + certificate-bound token 대안)
|
|
- [[raw/official-docs/spring-security-resource-server-jwt]] (Spring 벤더 구현 — clock skew default 등 구체값)
|
|
- 인용하는 branch:
|
|
- [[raw/branch-notes/feature-security-operational-baseline]]
|
|
- 인용하는 wiki: (미작성)
|