88 lines
8.0 KiB
Markdown
88 lines
8.0 KiB
Markdown
---
|
|
title: official-doc / Spring Security — JwtTimestampValidator Default Clock Skew (60 seconds)
|
|
source_type: official-doc
|
|
url: https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/jwt.html
|
|
archive_url:
|
|
related_branches: [feature-security-operational-baseline]
|
|
related_projects: [ca-skeleton]
|
|
tags: [official-doc, ca-skeleton, security, spring-security, clock-skew, jwt-validation]
|
|
created: 2026-06-08
|
|
last_reviewed: 2026-06-08
|
|
status: raw
|
|
confidence: high
|
|
vendor: Spring Security (VMware / Broadcom)
|
|
---
|
|
|
|
# Spring Security — JwtTimestampValidator Default Clock Skew (60 seconds)
|
|
|
|
> Layer: `raw/official-docs/` — Spring Security Reference 의 "Configuring Timestamp Validation" 섹션 verbatim 발췌.
|
|
> `feature-security-operational-baseline` D2 (clock skew tolerance = 60s) 의 Spring 벤더 doc 근거.
|
|
|
|
## Parent / 활용 branch (필수)
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-security-operational-baseline]] | D2 — clock skew tolerance = 60s. Spring Security 의 `JwtTimestampValidator` default leeway 가 60초임을 벤더 문서로 확인, 명시 `.clockSkew()` 설정 없이 default 에 의존하는 구현의 근거 |
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/jwt.html
|
|
- 아카이브 URL: (미수집)
|
|
- 저자 / 조직: Spring Security (VMware / Broadcom)
|
|
- 발행일: rolling docs (current = Spring Security 6.x)
|
|
- 마지막 확인일: 2026-06-08
|
|
|
|
## 왜 저장했는지 / Why archived
|
|
|
|
`feature-security-operational-baseline` D2 는 clock skew tolerance 를 60s 로 결정하되, 코드에서 `.clockSkew(Duration.ofSeconds(60))` 를 명시하지 않고 Spring `JwtTimestampValidator` 의 default leeway 에 의존한다. RFC 7519 는 "a few minutes" 상한만 명시하고 exact value 는 implementer 재량이므로, Spring 벤더 문서에서 default = 60s 임을 직접 확인해 D2 의 "60s 는 Spring default 와 일치한다는 가정"을 증거로 대체한다.
|
|
|
|
## 핵심 인용 / Key quotes (verbatim)
|
|
|
|
> [§Configuring Timestamp Validation — Default Clock Skew] "By default, Resource Server configures a clock skew of 60 seconds."
|
|
|
|
> [§Configuring Timestamp Validation — Configuration Example] "new JwtTimestampValidator(Duration.ofSeconds(60)),"
|
|
|
|
> [§Configuring Timestamp Validation — Key Points] "The default skew of 60 seconds is applied automatically"
|
|
|
|
> [§JwtTimestampValidator Javadoc — Class description] "Because clocks can differ between the Jwt source, say the Authorization Server, and its destination, say the Resource Server, there is a default clock leeway exercised when deciding if the current time is within the Jwt's specified operating window"
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| SS-JTVC-C1 | Spring Security Resource Server 는 기본적으로 60초의 clock skew 를 `JwtTimestampValidator` 에 적용한다 | [§Configuring Timestamp Validation] "By default, Resource Server configures a clock skew of 60 seconds." | `official-vendor-doc` | Spring Security OAuth2 Resource Server (servlet, 6.x), auto-config 사용 시 | 이 default 가 Spring Security 모든 버전에서 동일하다는 보장은 아님 (버전 확인 필요); WebFlux/reactive 스택의 동작은 별도 확인 필요 |
|
|
| SS-JTVC-C2 | `JwtTimestampValidator` 는 `Duration clockSkew` 파라미터로 명시적 clock skew 를 설정할 수 있으며, 권장 예시는 `Duration.ofSeconds(60)` | [§Configuring Timestamp Validation] "new JwtTimestampValidator(Duration.ofSeconds(60))," | `official-vendor-doc` | Spring Security JWT timestamp validation 커스터마이징 | `Duration.ofSeconds(60)` 이 표준 권고값이라는 의미는 아님 — 문서 예시 코드에서 default 60s 를 그대로 명시한 것 |
|
|
| SS-JTVC-C3 | `JwtTimestampValidator` 기본 생성자(`new JwtTimestampValidator()`)는 default max clock skew 를 사용한다 | [§JwtTimestampValidator Javadoc] "A basic instance with no custom verification and the default max clock skew" | `official-reference` | `JwtTimestampValidator` 기본 생성자 사용 시 | 이 Javadoc 인용만으로는 default max clock skew 의 정확한 Duration 값을 확정할 수 없음 — SS-JTVC-C1 과 결합해야 60s 로 확정 |
|
|
| SS-JTVC-C4 | `JwtTimestampValidator` 는 clock 이 Jwt source(Authorization Server) 와 destination(Resource Server) 사이에 다를 수 있어 default clock leeway 를 두고 있다 | [§JwtTimestampValidator Javadoc] "Because clocks can differ between the Jwt source, say the Authorization Server, and its destination, say the Resource Server, there is a default clock leeway exercised when deciding if the current time is within the Jwt's specified operating window" | `official-reference` | `JwtTimestampValidator` 의 설계 의도 | leeway 의 정확한 Duration 값은 이 인용 자체로는 미명시 — SS-JTVC-C1 로 60s 확인 |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- 이 자료가 직접 증명하는 것:
|
|
- `SS-JTVC-C1`: Spring Security Resource Server 의 default clock skew = **60초**. `feature-security-operational-baseline` D2 의 "Spring default 일치" 가정을 벤더 문서로 확증.
|
|
- `SS-JTVC-C2`: 명시 설정 시 `Duration.ofSeconds(60)` 을 `JwtTimestampValidator` 에 전달하는 패턴.
|
|
- `SS-JTVC-C3`: 기본 생성자가 default max clock skew 를 사용한다는 Javadoc 확인.
|
|
- `SS-JTVC-C4`: clock leeway 도입의 설계 근거 (Authorization Server ↔ Resource Server clock drift).
|
|
- 이 자료가 증명하지 않는 것:
|
|
- Spring Security 버전 변경 시 default 60s 가 유지된다는 보장 — 버전 고정 또는 명시 설정 권장.
|
|
- Spring Security WebFlux/reactive 스택의 default clock skew 동작 — 별도 reactive 문서 확인 필요.
|
|
- NTP drift > 60s 환경에서 60s leeway 가 충분한지 — 운영 환경 관측 필요 (D2 Open Risk 로 유지).
|
|
- `.clockSkew()` 명시 설정 없이 auto-config 만으로 60s 가 적용되는지의 세부 auto-config 동작 경로.
|
|
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
|
|
- ca-tmpl `src/` 코드에서 `.clockSkew()` 명시 설정 없이 auto-config 가 `JwtTimestampValidator(default)` 를 wiring 하는 경로 확인 (integration test: 61s expired token reject 확인).
|
|
- Spring Security 버전이 6.x 인지 확인 (본 문서 기준 버전).
|
|
|
|
## 메모 / Notes
|
|
|
|
- `feature-security-operational-baseline` `§Claims To Verify` 의 첫 번째 항목 (`Spring JwtTimestampValidator 의 default leeway 가 60s 와 일치`) 은 본 문서로 **벤더 doc 근거 확보** 완료. 그러나 integration test (61s expired token reject) 는 여전히 미검증 — `needs-implementation-test` 상태 유지.
|
|
- Javadoc URL (`/api/...JwtTimestampValidator.html`) 에서는 정확한 60s 수치를 명시하지 않음 (WebFetch 결과 확인). reference doc URL (`/reference/servlet/oauth2/resource-server/jwt.html`) 의 "Configuring Timestamp Validation" 섹션에서 "By default, Resource Server configures a clock skew of 60 seconds." 를 직접 확인.
|
|
- 기존 `raw/official-docs/spring-security-resource-server-jwt.md` 는 동일 URL 에서 keycloak-patterns 관련 claims (issuer-uri, JWKS, audience, role mapping) 를 추출한 파일임. 본 파일은 clock skew 에만 집중한 **별도 focused source** — 동일 URL 에서 다른 Claims 를 목적별로 분리 관리.
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 official-doc:
|
|
- [[raw/official-docs/security-jwt-rfc-7519-validation]] — RFC 7519 claim 검증 표준 (D2 의 RFC 측 근거: "a few minutes" leeway 상한)
|
|
- [[raw/official-docs/spring-security-resource-server-jwt]] — 동일 Spring reference URL 에서 keycloak-patterns 관련 claims (issuer-uri, audience, JWKS, role mapping) 추출 파일
|
|
- [[raw/official-docs/jwks-nimbus-jose-jwksourcebuilder-spring-integration]] — D10 JWKS cache/refresh 메커니즘
|
|
- 이 자료를 인용한 branch:
|
|
- [[raw/branch-notes/feature-security-operational-baseline]] — D2 clock skew 60s
|