llm-wiki/raw/official-docs/keycloak-refresh-token-rotation-reuse-admin-official.md

title, source_type, url, archive_url, related_branches, related_projects, tags, created

title	source_type	url	archive_url	related_branches	related_projects	tags	created
official-doc / Keycloak — "Revoke Refresh Token" 설정 정의 + "Refresh Token Max Reuse"/reuse-detection 부재 확인 (Server Administration Guide, Tokens tab)	official-doc	https://www.keycloak.org/docs/latest/server_admin/#_timeouts		feature-keycloak-refresh-rotation-and-logout feature-keycloak-refresh-token-rotation	keycloak-patterns	official-doc keycloak-patterns auth keycloak oidc	2026-07-18

official-doc / Keycloak — "Revoke Refresh Token" 설정 정의 + "Refresh Token Max Reuse"/reuse-detection 부재 확인

Layer: raw/ — 외부 자료(공식 문서 / 대기업 기술 블로그)의 원문 발췌·출처 기록. 본 템플릿은 raw/official-docs/ 와 raw/company-tech-blogs/ 두 폴더가 공유. 검증된 요약은 /ingest 후 wiki/concepts/에 source-summary-template 형식으로 별도 작성. 원본은 raw에 영구 보관.

source_type 허용값

• official-doc — 공식 레퍼런스 / 표준 / 사양 (Keycloak 공식 문서, Red Hat 운영)

Parent / 활용 branch (필수, 최소 1개+)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-keycloak-refresh-rotation-and-logout	D1(rotation ON + Refresh Token Max Reuse 0 강제 — stolen token 탐지)과 D5(RT_1 사용 → AT_2+RT_2 발급 → RT_1 재사용 → family 전체 invalidate → 재로그인 강제 시연)의 Keycloak 측 근거. 부분 해소만 가능 — "Revoke Refresh Token" 토글 정의는 확인되나, "Refresh Token Max Reuse" 설정명과 "재사용 시 family 전체 invalidate" 동작의 verbatim 은 이 공식 문서에서 확인되지 않음(아래 Claims Extracted C6, Usage Boundaries 참조) — D1/D5 는 UNSUPPORTED_DECISION 라벨을 유지해야 함
raw/branch-notes/feature-keycloak-refresh-token-rotation	동일 소스가 이 sibling branch(P2A)의 D1(rotation 활성화 — Revoke Refresh Token ON + Refresh Token Max Reuse 0 — reuse detection 으로 stolen token 탐지) 및 D4(rotation flow 4단계 — 재사용 시 family invalidate)에도 그대로 적용됨. 이 branch의 Decision Evidence Map 이 이미 동일한 gap("Keycloak 의 정확한 UI 항목 라벨"·"family invalidate 동작의 구체적 verbatim 부재")을 UNSUPPORTED_DECISION 으로 명시해 둔 상태이며, 본 raw는 그 gap 확인을 공식적으로 뒷받침(negative finding)한다

출처 / Source

• 원본 URL: https://www.keycloak.org/docs/latest/server_admin/#_timeouts (§Managing user sessions → Session and token timeouts → "Tokens tab" 테이블)
• 아카이브 URL: (미수집)
• 저자 / 조직: Keycloak (Red Hat) — Server Administration Guide
• 발행일: rolling docs. 페이지 내 "Report an issue" GitHub 링크 메타데이터에 version=26.7.0 명시 — Keycloak 26.7.0 ("latest") 문서.
• 마지막 확인일: 2026-07-18

⚠️ Fetch 방법론 기록: WebFetch 도구로 1차 시도했으나 페이지가 너무 커서(1.8MB) 도구 내부 처리 모델이 목표 섹션(Tokens tab)에 도달하기 전에 응답을 잘라(truncate) "해당 섹션이 제공된 콘텐츠에 없다"고 반환함 (2회 재시도, 앵커 #tokens/#_offline-access 포함해도 동일). 이에 curl로 동일 URL을 직접 fetch(HTTP 200, 1,846,056 bytes)하여 원문 HTML을 확보하고, 태그 제거 + HTML entity 디코딩(html.unescape)만 적용한 순수 텍스트를 self-grep 대상 파일로 저장했다 — 요약/재서술 없이 원문 그대로. 이 원문에 대해 grep -o -i "reuse" 전수 검색을 실행해 "Refresh Token Max Reuse" 문구와 "reuse detection"/"family" 관련 문구의 부재를 직접 확인했다(아래 Claims Extracted C6).

왜 저장했는지 / Why archived

두 sibling branch(P3A feature-keycloak-refresh-rotation-and-logout, P2A feature-keycloak-refresh-token-rotation)가 공통으로 "Revoke Refresh Token"/"Refresh Token Max Reuse" 설정과 재사용 탐지(reuse detection → family invalidate) 동작을 UNSUPPORTED_DECISION으로 표시하고 있다. 이 자료는 Keycloak 공식 Server Administration Guide "Tokens tab"에서 "Revoke Refresh Token" 설정의 공식 정의를 verbatim으로 확보하는 한편, "Refresh Token Max Reuse"라는 설정명과 family-invalidate 동작 문구가 이 공식 문서에는 존재하지 않는다는 사실을 전수 검색으로 확정해, 두 branch의 gap을 추측이 아닌 근거 있는 gap으로 명확히 한다.

핵심 인용 / Key quotes (verbatim, 5문장)

[§Managing user sessions → Session and token timeouts → Tokens tab] "Revoke Refresh Token: When Enabled, Keycloak revokes refresh tokens and issues another token that the client must use. This action applies to OIDC clients performing the refresh token flow."

[§Managing user sessions → Session and token timeouts → Tokens tab] "Access Token Lifespan: When Keycloak creates an OIDC access token, this value controls the lifetime of the token."

[§Managing user sessions → Offline access] "If you enable the Revoke Refresh Token option, you can use each offline token once only. After refresh, you must store the new offline token from the refresh response instead of the previous one."

[§Compromised access and refresh tokens] "Keycloak includes several actions to prevent malicious actors from stealing access tokens and refresh tokens. The crucial action is to enforce SSL/HTTPS communication between Keycloak and its clients and applications. Keycloak does not enable SSL by default."

[§Compromised access and refresh tokens] "Another action to mitigate damage from leaked access tokens is to shorten the token’s lifespans. You can specify token lifespans within the timeouts page. Short lifespans for access tokens force clients and applications to refresh their access tokens after a short time. If an admin detects a leak, the admin can log out all user sessions to invalidate these refresh tokens or set up a revocation policy."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
KC-ROT-C1	"Revoke Refresh Token" 설정을 Enabled로 하면 Keycloak은 refresh token을 revoke하고, client가 반드시 사용해야 하는 다른(새) 토큰을 발급한다. 이 동작은 refresh token flow를 수행하는 OIDC client에 적용된다	[Tokens tab] "When Enabled, Keycloak revokes refresh tokens and issues another token that the client must use. This action applies to OIDC clients performing the refresh token flow."	official-vendor-doc	D1(양쪽 branch)의 "Revoke Refresh Token = ON" 설정이 실제로 rotation(사용된 RT 무효화 + 새 토큰 발급)을 의미한다는 것의 1차 근거	이미 무효화된 refresh token이 다시 제출되었을 때(재사용 시도) 정확히 무슨 응답이 오는지, 그 무효화 범위가 해당 토큰 1개인지 세션/family 전체인지는 이 문장만으로 증명 안 됨
KC-ROT-C2	(offline token 한정) "Revoke Refresh Token" 옵션을 활성화하면 offline token은 1회만 사용 가능하며, refresh 후에는 이전 offline token 대신 응답으로 받은 새 offline token을 저장해야 한다	[Offline access] "If you enable the Revoke Refresh Token option, you can use each offline token once only. After refresh, you must store the new offline token from the refresh response instead of the previous one."	official-vendor-doc	offline_access scope 로 발급된 offline token 의 single-use rotation 요구사항 — "Revoke Refresh Token" 이 rotation을 강제한다는 KC-ROT-C1 을 offline 시나리오에서 보강	일반(비-offline) refresh token에 대해서도 문자 그대로 "once only"라고 명시하진 않음(그 일반 케이스는 KC-ROT-C1로 커버). "이전 토큰을 다시 쓰면 어떻게 되는가"(reuse 시 구체적 결과)는 이 문장도 명시하지 않음
KC-ROT-C3	"Access Token Lifespan" 설정은 Keycloak이 생성하는 OIDC access token의 lifetime(수명)을 제어하는 값이다	[Tokens tab] "When Keycloak creates an OIDC access token, this value controls the lifetime of the token."	official-vendor-doc	D2(Access Token Lifespan 5분) 결정에서 언급하는 설정명 자체가 Keycloak 공식 설정임을 확인	"5분"이라는 구체적 권장값이나 짧은 lifespan의 트레이드오프 근거는 이 문장에 없음(그건 KC-ROT-C5가 별도로 뒷받침)
KC-ROT-C4	Keycloak은 access token과 refresh token 탈취를 막기 위한 여러 조치를 포함하며, 핵심 조치는 Keycloak과 client/application 간 SSL/HTTPS 통신을 강제하는 것이다. Keycloak은 기본적으로 SSL을 활성화하지 않는다	[Compromised access and refresh tokens] "Keycloak includes several actions to prevent malicious actors from stealing access tokens and refresh tokens. The crucial action is to enforce SSL/HTTPS communication between Keycloak and its clients and applications. Keycloak does not enable SSL by default."	official-vendor-doc	토큰 탈취 방어에 대한 Keycloak 공식 위협모델 배경 설명(일반 원칙)	rotation/max-reuse 자체를 언급하지 않음 — SSL 강제라는 별개의 방어선에 대한 문장
KC-ROT-C5	탈취된 access token의 피해를 완화하는 또 다른 조치는 토큰의 lifespan을 짧게 하는 것이다. 짧은 access token lifespan은 client가 짧은 시간 후 access token을 다시 갱신하도록 강제한다. admin이 유출을 감지하면 모든 user session을 로그아웃시켜 refresh token을 invalidate하거나 revocation policy를 설정할 수 있다	[Compromised access and refresh tokens] "Another action to mitigate damage from leaked access tokens is to shorten the token’s lifespans. [...] If an admin detects a leak, the admin can log out all user sessions to invalidate these refresh tokens or set up a revocation policy."	official-vendor-doc	D2(Access Token Lifespan 5분 — revoke 함정 짧은 대기로 검증) 결정의 원칙적 정당화 — "짧은 lifespan → 유출 피해 완화"가 Keycloak 공식 권고임을 확인	"5분"이라는 정확한 수치를 권장하지 않음(일반 원칙만 제공). 또한 이 문장은 admin의 수동 개입(세션 로그아웃/revocation policy 설정)을 설명하는 것이지, "재사용된 refresh token을 Keycloak이 자동으로 탐지해 family를 invalidate한다"는 D1/D5의 자동 reuse-detection 메커니즘을 증명하지 않음
KC-ROT-C6	(부재 확인/negative finding) 이 페이지(Keycloak 26.7.0 Server Administration Guide 전체, 1,846,056 bytes)를 전수 검색(grep -o -i "reuse")한 결과, "Refresh Token Max Reuse"라는 설정명은 어디에도 나타나지 않으며, "재사용된(이미 사용된) refresh token이 다시 제출되면 token family 전체가 invalidate된다"는 취지의 문구도 발견되지 않는다	(인용 없음 — 부재 확인. grep -nF -- "Refresh Token Max Reuse" 및 grep -o -i "reuse" 실행 결과 "reuse"라는 단어 자체가 0회 매치)	needs-confirmation	D1/D5(양쪽 branch)의 "Refresh Token Max Reuse" 설정 라벨 및 "재사용 시 family 전체 invalidate" 자동 동작 주장에 대한 gap 확인 — 이 raw는 그 주장을 지지도 반박도 하지 않으며, "공식 문서에 텍스트로 서술되어 있지 않다"는 사실만 확정한다	이 설정이 Keycloak 어드민 콘솔 UI에 실제로 존재하지 않는다는 뜻은 아니다. "Tokens Tab" 스크린샷(./images/tokens-tab.png) 자체에는 필드가 있을 수 있으나 이미지 픽셀은 텍스트 grep 대상이 아님 — UI 캡처로 별도 확인 필요

Strength 허용값

• official-vendor-doc — KC-ROT-C1~C5, Keycloak 공식 Server Administration Guide 원문에서 직접 발췌
• needs-confirmation — KC-ROT-C6, 원문 부재를 확인한 negative finding (원문이 증명하지도 반증하지도 않음)

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:
  • KC-ROT-C1: "Revoke Refresh Token" 토글의 공식 정의 — Enabled 시 사용된 refresh token을 revoke하고 새 토큰 발급(= rotation)
  • KC-ROT-C2: offline token 시나리오에서 동일 토글의 single-use 요구사항
  • KC-ROT-C3: "Access Token Lifespan" 설정명과 역할
  • KC-ROT-C4~C5: 짧은 access token lifespan이 유출 피해 완화라는 Keycloak 공식 위협모델 원칙
  • KC-ROT-C6: "Refresh Token Max Reuse" 설정명과 "재사용 시 family 전체 invalidate" 동작 문구가 이 공식 문서 텍스트에는 부재하다는 사실
• 이 자료가 증명하지 않는 것:
  • "Refresh Token Max Reuse" 설정이 Keycloak 26.x admin 콘솔 UI에 실제로 존재하는지, 존재한다면 정확한 라벨이 무엇인지 (branch-note 본문에 언급된 "Refresh Token Max Reuse: 0"은 실무 경험/타 자료 기반 서술로 보이나, 본 raw로는 확인 불가)
  • 이미 사용된 refresh token이 재사용될 때 Keycloak이 자동으로 그 사실을 탐지해 관련된 모든 토큰(family)을 invalidate한다는 구체적 메커니즘 — 본 raw는 이를 서술하지 않음(D1/D5의 핵심 주장은 여전히 UNSUPPORTED_DECISION)
  • Keycloak 버전(25.x vs 26.7.0)에 따른 admin UI 라벨 차이
• 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  • Keycloak 25.x/26.x 실제 admin 콘솔의 Realm Settings → Tokens 탭을 직접 캡처하여 "Refresh Token Max Reuse" 필드의 실재 여부와 정확한 라벨 확인
  • Keycloak 소스 코드(server 구현) 또는 release notes 에서 refresh token reuse detection 알고리즘(family invalidate) 관련 서술 검색
  • docker-compose 실험으로 RT 재사용 시 실제 응답(4xx) 과 family 전체 invalidate 여부 실측 (양쪽 branch의 Claims To Verify 표에 이미 계획됨)

메모 / Notes

나중에 wiki로 옮길 때 참고할 짧은 메모. 검증되지 않은 내 추론은 여기에 두지 말 것.

• 이 raw 문서의 핵심 가치는 "확인함"이 아니라 "부재를 확인함"이다 — D1/D5를 UNSUPPORTED_DECISION에서 벗어나게 하려면 Keycloak admin UI 실측 캡처 또는 Keycloak 소스/release-notes 레벨의 별도 raw가 추가로 필요하다.
• WebFetch 도구가 큰 단일 페이지(1.8MB)에서 목표 섹션 도달 전에 truncate하는 실패 패턴을 재확인 — 동일 현상이 sibling raw(keycloak-oidc-logout-endpoint-official)에서는 발생하지 않았는데, 그 문서는 앵커된 상대적으로 앞쪽 섹션(RP-Initiated Logout)을 겨냥했고, 본 조사 대상(Tokens tab, "Session and token timeouts")은 페이지 중반부(약 7000번째 줄, 전체 HTML의 상당히 안쪽)라 truncate 위험이 더 큼. 향후 이 페이지의 더 뒷부분 섹션을 조사할 때도 curl 직접 fetch를 우선 고려할 것.
• 추가로 봐야 할 동일 출처 페이지: 이 페이지의 "Client Policies" 챕터(설정 가능한 executor 목록)에 refresh token 관련 policy executor가 있는지 미확인 — 후속 raw 후보.

Related / 관련

• raw/official-docs/keycloak-securing-apps-overview-official — Keycloak Securing Apps 개요. 두 인용 branch가 기존에 인용하던 자료이나 rotation/max-reuse 관련 verbatim 없음(양쪽 Decision Evidence Map에 명시됨)
• raw/official-docs/keycloak-oidc-logout-endpoint-official — 동일 server_admin 페이지의 다른 섹션(RP-Initiated Logout)을 다루는 sibling raw. 이 문서가 성공적으로 fetch됨을 근거로 본 조사의 fallback 판단(같은 페이지 재시도)에 사용됨
• raw/official-docs/oauth-v2-1-draft-ietf — 양쪽 branch가 인용하는 OAuth 2.1 draft (rotation 권고 배경, Keycloak 특유 동작과는 별개)
• 인용하는 branch: raw/branch-notes/feature-keycloak-refresh-rotation-and-logout, raw/branch-notes/feature-keycloak-refresh-token-rotation
• 인용한 wiki: (미작성)