Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

9.0 KiB

Raw Permalink Blame History

title, source_type, url, archive_url, status, confidence, related_branches, related_projects, tags, created, last_reviewed

title

source_type

url

archive_url

status

confidence

related_branches

related_projects

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) 위임.

같은 주제 다른 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: (미작성)

9.0 KiB Raw Permalink Blame History