Files

T

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

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

10 KiB

Raw Permalink Blame History

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

Keycloak Server Admin — Realm Keys / Active-Passive Key Rotation + JWKS Overlap Window

Layer: raw/official-docs/ — Keycloak 공식 서버 관리 가이드에서 확인한 realm key rotation (active/passive 모델) + 권고 rotation 주기. D10 의 rotation overlap window 24h 의 mechanism 근거 (정확한 숫자는 미명세 — project trade-off 유지).

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-security-operational-baseline	D10: rotation overlap window 24h 의 근거 (Keycloak 이 active/passive key 를 JWKS 에 동시 노출하는 메커니즘을 공식 지원한다는 사실)

출처 / Source

원본 URL: https://www.keycloak.org/docs/latest/server_admin/index.html#realm-keys
보완 URL (Duende IdentityServer key management): https://docs.duendesoftware.com/identityserver/fundamentals/key-management/
아카이브 URL: (미수집)
저자 / 조직: Red Hat / Keycloak Project + Duende Software (보완)
마지막 확인일: 2026-06-08

왜 저장했는지 / Why archived

Keycloak 이 signing key rotation 시 old key 를 JWKS 에서 즉시 제거하지 않고 passive 상태로 유지한다는 것을 공식 문서에서 확인하기 위해. 이것이 rotation overlap window 의 IdP-side 메커니즘. resource server 가 24h overlap 을 기다리는 것이 Keycloak 의 "over time all tokens will use new keys" 패턴과 일치하는지 판단 근거.

핵심 인용 / Key quotes (verbatim)

[Keycloak Server Admin §Realm Keys] "Keycloak has a single active key pair at a time, but can have several passive keys as well. The active key pair is used to create new signatures, while the passive key pair can be used to verify previous signatures."

[Keycloak Server Admin §Realm Keys] "Start by creating new keys with a higher priority than the existing active keys. You can instead create new keys with the same priority and making the previous keys passive."

[Keycloak Server Admin §Realm Keys] "all new tokens and cookies will be signed with the new keys. When a user authenticates to an application the SSO cookie is updated with the new signature. When OpenID Connect tokens are refreshed new tokens are signed with the new keys. This means that over time all cookies and tokens will use the new keys and after a while the old keys can be removed."

[Keycloak Server Admin §Realm Keys, rotation cadence recommendation] "Consider creating new keys every three to six months and deleting old keys one to two months after you create the new keys."

[Duende IdentityServer Key Management docs] "The default is to rotate keys every 90 days, announce new keys with 14 days of propagation time, retain old keys for a duration of 14 days, and to delete keys when they are retired."

[Duende IdentityServer Key Management docs] "After a new key becomes the active signing credential, the previous key 'is retired, but kept in discovery for a configurable RetentionDuration.' The default retention period is 14 days."

[Auth0 Rotate Signing Keys docs] "The OIDC discovery document will always include both the current key and the next key, and it may also include the previous key if the previous key has not yet been revoked."

[Auth0 Rotate Signing Keys docs] "all tokens signed with the previous key will still be valid until you revoke the previous key."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
KC-ROT-C1	Keycloak 은 한 번에 하나의 active key pair + 여러 passive key pair 를 유지하며, passive key 는 이전 signature 검증에만 사용된다	[Keycloak Server Admin §Realm Keys] "Keycloak has a single active key pair at a time, but can have several passive keys as well. The active key pair is used to create new signatures, while the passive key pair can be used to verify previous signatures."	`official-vendor-doc`	Keycloak realm key 관리 — 모든 token 타입 (JWT, SSO cookie)	Keycloak 이 JWKS 엔드포인트에 passive key 를 얼마나 오래 노출하는지의 exact 기간 (수동 삭제 전까지 = rotation 주기에 따라 1~2개월이 권고이나 강제 아님)
KC-ROT-C2	새 key 를 생성하면 모든 신규 token 은 새 key 로 서명되며, 기존 token 은 점진적으로 갱신될 때 새 key 로 재서명된다	[Keycloak Server Admin §Realm Keys] "all new tokens and cookies will be signed with the new keys. [...] This means that over time all cookies and tokens will use the new keys and after a while the old keys can be removed."	`official-vendor-doc`	Keycloak realm key rotation (priority 기반 active key 교체)	"after a while" 의 정확한 기간 — token TTL 에 따라 다르므로 project 결정 필요
KC-ROT-C3	Keycloak 공식 권고 rotation 주기: 새 key 생성은 3~~6개월마다, 이전 key 삭제는 새 key 생성 후 1~~2개월 후	[Keycloak Server Admin] "Consider creating new keys every three to six months and deleting old keys one to two months after you create the new keys."	`official-vendor-doc`	Keycloak 운영 환경에서의 rotation 주기 권고	이 수치가 모든 token TTL, access 패턴에 최적임을 보장하지 않음 — "Consider" 는 normative 강제가 아님
KC-ROT-C4	Duende IdentityServer 는 기본적으로 90일마다 key rotation, 14일 propagation time (새 key 가 공개되지만 서명에 미사용), 14일 retention (rotation 후 이전 key 를 JWKS 에 유지)	[Duende IdentityServer Key Management] "The default is to rotate keys every 90 days, announce new keys with 14 days of propagation time, retain old keys for a duration of 14 days, and to delete keys when they are retired."	`official-vendor-doc`	Duende IdentityServer (ASP.NET Core IdP) — Keycloak 과 다른 제품이지만 overlap window 개념의 비교 reference	이 수치가 Keycloak 에 직접 적용됨을 증명하지 않음; OIDC 생태계에서 overlap window 개념이 표준화된 방식으로 구현됨을 보여주는 사례
KC-ROT-C5	Auth0 는 OIDC discovery document 에 current key + next key (예정) + previous key (미폐기 시) 를 동시 포함시킨다	[Auth0 docs] "The OIDC discovery document will always include both the current key and the next key, and it may also include the previous key if the previous key has not yet been revoked."	`official-vendor-doc`	Auth0 tenant — Keycloak 과 다른 제품이지만 JWKS 다중 key 동시 노출 패턴의 비교 reference	Auth0 의 이 동작이 Keycloak 에 동일하게 적용됨을 증명하지 않음
KC-ROT-C6	rotation overlap window 의 안전한 최소값은 "overlap window = token TTL + JWKS cache TTL + 10분" 이다 (WorkOS guide 공식화)	[WorkOS JWKS guide] "overlap window = token TTL + JWKS cache TTL + 10 minutes"	`engineering-blog` (WorkOS — IdP vendor 기술 블로그, authoritative engineering blog 수준)	JWT access token TTL 이 있는 모든 OAuth2/OIDC resource server	이 공식이 RFC 나 공식 표준으로 normative 하게 확정된 것은 아님 — engineering best practice 수준

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- KC-ROT-C1: Keycloak 의 active/passive key 동시 유지 메커니즘 존재
- KC-ROT-C2: 새 key 가 즉시 신규 token 서명에 사용되며 기존 token 은 점진적 전환
- KC-ROT-C3: Keycloak 공식 권고 rotation 주기 (3~~6개월 생성, 1~~2개월 후 삭제) — 이 1~2개월이 overlap window 하한선 참고값
- KC-ROT-C4: OIDC 생태계에서 14일 propagation + 14일 retention (Duende) 이 일반적인 production 값
- KC-ROT-C5: JWKS 에 multiple active key 를 동시 노출하는 것이 IdP (Auth0, Keycloak) 에서 표준 패턴
- KC-ROT-C6: rotation overlap window 최소값 공식 (token TTL + cache TTL + buffer)
이 자료가 증명하지 않는 것:
- rotation overlap window 를 정확히 "24h" 로 설정해야 하는 근거 — 24h 는 project trade-off (access token TTL 의 상한 추정 + idempotency TTL 정합 — 본 raw 범위 밖)
- Keycloak 이 passive key 를 JWKS 에 명시적으로 몇 시간/일 동안 유지하는지의 default 값
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-tmpl 의 JWT access token TTL 실제값 확인 → KC-ROT-C6 공식으로 minimum overlap 계산
- Keycloak admin API 또는 UI 에서 passive key 를 JWKS 에 유지하는 기간 설정 방법 확인
- rotation overlap 24h 가 idempotency TTL 24h 와 정합하는 invariant 의 contract test 작성

메모 / Notes

Keycloak 의 "delete old keys one to two months after you create the new keys" (KC-ROT-C3) 는 ca-tmpl 의 24h overlap 과 스케일이 다름 — Keycloak 권고는 수동 운영 주기이고, 24h 는 resource server 가 old kid 를 유효로 수락하는 on-demand window.
KC-ROT-C4 (Duende 14일 retention) 와 KC-ROT-C6 (WorkOS 공식) 모두 ca-tmpl 의 24h 보다 길다. 24h 선택이 idempotency TTL 정합에서 나온 project-specific constraint 임을 branch-note D10 에 명시해야 함.
여러 IdP (Auth0, Duende, Keycloak) 가 모두 JWKS 에 multiple key 동시 노출을 지원한다는 사실이 overlap window 설계의 IdP 측 전제 조건을 확인해준다.

raw/official-docs/jwks-nimbus-jose-jwksourcebuilder-spring-integration — resource server 측 JWKS 캐시/refresh 메커니즘 (본 파일과 complementary)
raw/official-docs/security-jwt-rfc-7519-validation — JWT claim 검증 표준
raw/branch-notes/feature-security-operational-baseline — D10 결정 컨텍스트

10 KiB Raw Permalink Blame History