---
title: WorkOS — The Developer's Guide to JWKS (unknown-kid on-demand refresh, rate-limit pattern, overlap window formula)
source_type: company-tech-blog
url: https://workos.com/blog/developers-guide-jwks
archive_url:
related_branches: [feature-security-operational-baseline]
related_projects: [ca-skeleton]
tags: [jwks, jwt, key-rotation, unknown-kid, rate-limit, overlap-window, resource-server, company-tech-blog]
status: raw
confidence: medium
created: 2026-06-08
last_reviewed: 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초, `NIMBUS-JWKS-C1`)보다 훨씬 길다. ca-tmpl 의 1/min (60초) 는 Nimbus 기본값(30초)보다는 길고 WorkOS 권고(5~10분)보다는 짧음 — 이 위치를 trade-off 로 branch-note 에 명시.
- 이 자료의 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 결정 컨텍스트