7.2 KiB
title, source_type, url, archive_url, related_branches, related_projects, tags, status, confidence, created, last_reviewed
| title | source_type | url | archive_url | related_branches | related_projects | tags | status | confidence | created | last_reviewed | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| WorkOS — The Developer's Guide to JWKS (unknown-kid on-demand refresh, rate-limit pattern, overlap window formula) | company-tech-blog | https://workos.com/blog/developers-guide-jwks |
|
|
|
raw | medium | 2026-06-08 | 2026-06-08 |
WorkOS — The Developer's Guide to JWKS (unknown-kid on-demand refresh, rate-limit pattern, overlap window formula)
Layer:
raw/company-tech-blogs/— WorkOS 엔지니어링 블로그의 JWKS 운영 가이드. company-tech-blog = case study / engineering practice, 공식 best practice 로 승격 금지. D10 의 unknown kid rate-limit (5~10분 권고) + overlap window 공식 의 engineering practice 근거.
Parent / 활용 branch (필수)
| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| raw/branch-notes/feature-security-operational-baseline | D10: unknown kid on-demand refresh rate-limit (5~10분 권고) + rotation overlap window 공식 (token TTL + cache TTL + buffer) 의 engineering practice 근거 |
출처 / Source
- 원본 URL: https://workos.com/blog/developers-guide-jwks
- 아카이브 URL: (미수집)
- 저자 / 조직: WorkOS (IdP/Authentication-as-a-Service vendor)
- 마지막 확인일: 2026-06-08
왜 저장했는지 / Why archived
WorkOS 는 IdP vendor 로서 resource server 측에서 JWKS 를 어떻게 캐시하고, unknown kid 를 어떻게 처리하며, rotation overlap window 를 어떻게 설계해야 하는지에 대한 실무 패턴을 설명한다. 특히 thundering herd 방지를 위한 rate limit 의 권고 구간(5~10분)과 overlap window 공식이 이 자료에만 명시적으로 나온다.
핵심 인용 / Key quotes (verbatim)
[WorkOS JWKS guide §Unknown KID Handling] "If a JWT arrives with a kid not present in your cached JWKS, refetch the JWKS before rejecting the token"
[WorkOS JWKS guide §Rate Limiting] "implement a minimum refresh interval (typically 5–10 minutes)"
[WorkOS JWKS guide §Rate Limiting context] "To prevent abuse (e.g., an attacker flooding your service with tokens signed by unknown keys), implement a minimum refresh interval (typically 5–10 minutes)." [paraphrase reconstructed from verbatim fragment — see note below]
[WorkOS JWKS guide §Caching] "Cache the JWKS according to the Cache-Control headers returned by the endpoint."
[WorkOS JWKS guide §Caching example] Cache-Control: max-age=86400 (24시간 캐시 예시로 제시)
[WorkOS JWKS guide §Overlap Window] "overlap window = token TTL + JWKS cache TTL + 10 minutes"
Claims Extracted / 추출된 주장
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| WORKOS-JWKS-C1 | unknown kid 를 가진 JWT 가 도착하면 즉시 거부하기 전에 JWKS 를 재조회해야 한다 | "If a JWT arrives with a kid not present in your cached JWKS, refetch the JWKS before rejecting the token" | engineering-blog |
JWKS 기반 JWT 검증을 하는 resource server 일반 | 이 패턴이 RFC 나 공식 표준에서 normative 하게 요구되는 것은 아님 (공식 표준에는 unknown kid 처리 방식 미명세) |
| WORKOS-JWKS-C2 | unknown kid on-demand refresh 의 rate limit 권고값은 "5~10분" 이다 | "implement a minimum refresh interval (typically 5–10 minutes)" | engineering-blog |
JWKS 기반 JWT 검증 resource server — thundering herd 방지 목적 | 이 수치가 normative 하게 정해진 것이 아님; ca-tmpl 의 1/min (60초) 는 이 권고보다 작은 구간이므로 trade-off 명시 필요 |
| WORKOS-JWKS-C3 | JWKS 는 endpoint 가 반환하는 Cache-Control 헤더에 따라 캐시해야 한다 | "Cache the JWKS according to the Cache-Control headers returned by the endpoint." | engineering-blog |
JWKS endpoint 를 HTTP 로 조회하는 모든 resource server | IdP 가 Cache-Control 헤더를 반환하지 않는 경우의 fallback TTL 은 미명세 |
| WORKOS-JWKS-C4 | rotation overlap window 의 최소 안전값 공식: token TTL + JWKS cache TTL + 10분 | "overlap window = token TTL + JWKS cache TTL + 10 minutes" | engineering-blog |
JWT access token 기반 OAuth2 resource server 의 rotation overlap 설계 | 이 공식이 RFC 나 vendor 공식 문서에서 normative 하게 채택된 것은 아님; engineering practice 수준 |
Usage Boundaries / 적용 경계
- 이 자료가 직접 증명하는 것:
WORKOS-JWKS-C1: unknown kid → JWKS refetch before reject 패턴 (engineering practice)WORKOS-JWKS-C2: thundering herd 방지를 위한 rate limit 구간 5~10분 (engineering practice)WORKOS-JWKS-C3: Cache-Control 헤더 기반 JWKS 캐시 (engineering practice)WORKOS-JWKS-C4: overlap window = token TTL + cache TTL + 10분 공식 (engineering practice)
- 이 자료가 증명하지 않는 것:
- ca-tmpl 의 rate limit "1회/1분" 이 올바른 값임을 증명하지 않음 — WorkOS 권고(5~10분)보다 짧으므로 thundering herd 위험 증가 (WORKOS-JWKS-C2 와 충돌, trade-off 명시 필요)
- rotation overlap window "24h" 가 이 공식에서 도출됨을 증명하지 않음 — ca-tmpl 의 token TTL 이 불명확한 상태에서 24h 는 별도 trade-off
- 이 가이드가 RFC 나 공식 표준을 인용하는지 확인되지 않음 (공식 표준으로 승격 금지)
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-tmpl 의 JWT access token TTL 확인 → WORKOS-JWKS-C4 공식으로 minimum overlap window 계산 후 24h 정당화 또는 재검토
- ca-tmpl 의 JWKS cache TTL (10분) 확인 → overlap window = access_token_TTL + 10min + 10min 이 24h 보다 작은지 검증
- rate limit 1/min 이 5~10분 권고보다 짧은 것의 trade-off: rotation key가 매우 빠르게 전파되는 환경에서는 이점이 있으나, 공격자가 무작위 kid 로 DoS 시도 시 1/min 은 protection 이 약함
메모 / Notes
- WorkOS 는 IdP/AuthN-as-a-Service vendor 이므로 이 가이드는 IdP 를 운영하는 쪽과 resource server 를 운영하는 쪽 모두의 관점에서 쓰여 있다. resource server 관점의 권고임을 확인.
- "5
10분" 은 Nimbus JOSE+JWT 의 기본 rate limit (30초,10분)보다는 짧음 — 이 위치를 trade-off 로 branch-note 에 명시.NIMBUS-JWKS-C1)보다 훨씬 길다. ca-tmpl 의 1/min (60초) 는 Nimbus 기본값(30초)보다는 길고 WorkOS 권고(5 - 이 자료의 claim 은
company-case-study→engineering-blog강도이므로 별도 official-doc (RFC 7517, Spring Security ref) 과 교차 검증 필요. D10 을UNSUPPORTED_DECISION→ 부분 지지 상태로 격상시키기 위해서는 mechanism (NIMBUS-JWKS-C6) 의 공식 근거 + 이 engineering practice 를 함께 사용.
Related / 관련
- raw/official-docs/jwks-nimbus-jose-jwksourcebuilder-spring-integration — mechanism 공식 근거 (official-vendor-doc)
- raw/official-docs/jwks-keycloak-key-rotation-active-passive — rotation overlap window 의 IdP-side 근거
- raw/branch-notes/feature-security-operational-baseline — D10 결정 컨텍스트