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

---
title: Keycloak Server Administration Guide — Refresh Token Rotation & Session/Token Timeouts
source_type: official-doc
url: https://www.keycloak.org/docs/latest/server_admin/index.html
archive_url:
related_branches: [feature-keycloak-refresh-token-rotation]
related_projects: [keycloak-patterns]
tags: [official-doc, keycloak-patterns, auth, keycloak, oauth2, refresh-token-rotation]
created: 2026-07-18
status: raw
confidence: high
last_reviewed: 2026-07-18
---

# Keycloak Server Administration Guide — Refresh Token Rotation & Session/Token Timeouts

> Layer: `raw/official-docs/` — Keycloak 공식 Server Administration Guide 의 "Managing user sessions → Session and token timeouts" 절과 "Core concepts and terms → Refresh token grant → Refresh token rotation" 절 발췌.
> [[raw/branch-notes/feature-keycloak-refresh-token-rotation]]의 D1(rotation 활성화 결정) + D4(rotation flow 4단계) 를 뒷받침하는 근거로 수집.

## source_type 허용값

frontmatter `source_type:` 에는 다음 중 하나만 사용: `official-doc` — 공식 레퍼런스 / 표준 / 사양.

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

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-keycloak-refresh-token-rotation]] | D1(`Revoke Refresh Token: ON` 설정으로 rotation 활성화 — 단, "Refresh Token Max Reuse" 라는 별도 수치 파라미터는 본 자료에 **없음**, `Revoke Refresh Token` 은 Enabled/Disabled 토글 하나로만 문서화됨) 과 D4(RT 사용 후 즉시 invalidate → 새 RT 발급이라는 rotation flow 골격 — 단 "family 전체 invalidate" 표현은 본 자료에 **없음**) 의 부분적 근거. Access Token Lifespan / SSO Session Idle·Max / Client Session Idle·Max 정의는 timeout 관련 결정의 근거. |

## 출처 / Source

- 원본 URL: https://www.keycloak.org/docs/latest/server_admin/index.html
- 아카이브 URL: (미수집)
- 저자 / 조직: Keycloak (Red Hat) — Server Administration Guide (single-page, rolling "latest" 문서, 페이지 내 GitHub 편집 링크 기준 문서 버전 `26.7.0`)
- 발행일: rolling docs (버전 태그 `26.7.0` — 페이지 내 "Edit this section" / "Report an issue" 링크의 `version=` 쿼리 파라미터로 확인)
- 마지막 확인일: 2026-07-18

**URL 상태 확인 (필수 기록)**: 사용자가 사전에 우려했던 404/redirect 는 **발생하지 않음**. `curl -sL` 실측 결과 `HTTP_CODE:200`, `FINAL_URL:https://www.keycloak.org/docs/latest/server_admin/index.html` (요청 URL과 동일, redirect 없음), 응답 크기 1,846,056 bytes. 요청된 URL 이 그대로 유효한 단일 페이지("Server Administration Guide" 전체, TOC 포함)이며, "Session and token timeouts" 절은 앵커 `#_timeouts` 로, "Refresh token rotation" 절은 앵커 `#_refresh_token_rotation` 로 같은 페이지 내에 존재.

**WebFetch 도구 한계 기록**: 1차 시도로 Claude Code 내장 `WebFetch` 도구를 사용했으나, 이 도구는 내부적으로 소형 모델이 본문을 요약(paraphrase)하여 반환하므로 byte-exact verbatim 인용에 부적합했다 (TOC 항목만 나열한 요약을 반환, 실제 절 본문 텍스트 없음). 이에 `curl` 로 원본 HTML 을 직접 재확보하고, HTML 태그를 제거한 순수 텍스트로 정규화한 뒤 그 결과에 대해 Self-Grep 을 수행했다 — WebFetch 산출물이 아닌 curl 로 받은 원본 바이트가 검증 기준이다.

## 왜 저장했는지 / Why archived

`feature-keycloak-refresh-token-rotation` branch 의 D1(rotation 활성화 설정)·D4(rotation flow) 가 `UNSUPPORTED_DECISION` 으로 표시되어 있어, Keycloak 공식 문서에서 정확히 무엇이 검증되고 무엇이 검증되지 않는지 명확히 하기 위해 수집. 결과적으로 **부분 검증**: `Revoke Refresh Token` 토글의 존재와 동작은 확인되지만, branch 가 언급한 `Refresh Token Max Reuse` 수치 파라미터와 "family invalidate" 표현은 이 공식 문서에서 확인되지 않았다 — 이는 fabrication 을 피하기 위해 있는 그대로 기록한다.

## 핵심 인용 / Key quotes (verbatim, HTML 태그 제거 후 텍스트 기준)

> [§_timeouts, Tokens tab table — "Revoke Refresh Token" row] "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."

> [§_refresh_token_rotation, "Refresh token rotation"] "It is possible to specify that the refresh token is considered invalid once it is used. This means that client must always save the refresh token from the last refresh response because older refresh tokens, which were already used, would not be considered valid anymore by Keycloak. This is possible to set with the use of Revoke Refresh token option as specified in the timeouts section."

> [§_refresh_token_rotation, 이어지는 문단 — 대안: rotation 끄기] "Keycloak also supports the situation that no refresh token rotation exists. In this case, a refresh token is returned during login, but subsequent responses from refresh-token requests will not return new refresh tokens. This practice is recommended for instance in the FAPI 2 draft specification and FAPI 2 final specification in the securing apps section. In Keycloak, it is possible to skip refresh token rotation with the use of client policies. You can add executor suppress-refresh-token-rotation to some client profile and configure client policy to specify for which clients would be the profile triggered, which means that for those clients the refresh token rotation is going to be skipped."

> [§_timeouts, Tokens tab table — "Access Token Lifespan" row] "When Keycloak creates an OIDC access token, this value controls the lifetime of the token."

> [§_timeouts, Sessions tab table — "SSO Session Idle" row] "This setting is for OIDC clients only. If a user is inactive for longer than this timeout, the user session is invalidated. This timeout value resets when clients request authentication or send a refresh token request. Keycloak adds a window of time to the idle timeout before the session invalidation takes effect. See the note later in this section."

> [§_timeouts, Sessions tab table — "SSO Session Max" row] "The maximum time before a user session expires."

> [§_timeouts, Sessions tab table — "Client Session Idle" row] "Idle timeout for the client session. If the user is inactive for longer than this timeout, the client session is invalidated and the refresh token requests bump the idle timeout. This setting never affects the general SSO user session, which is unique. Note the SSO user session is the parent of zero or more client sessions, one client session is created for every different client app the user logs in. This value should specify a shorter idle timeout than the SSO Session Idle. Users can override it for individual clients in the Advanced Settings client tab. This setting is an optional configuration and, when set to zero, uses the same idle timeout in the SSO Session Idle configuration."

> [§_timeouts, Sessions tab table — "Client Session Max" row] "The maximum time for a client session and before a refresh token expires and invalidates. As in the previous option, this setting never affects the SSO user session and should specify a shorter value than the SSO Session Max. Users can override it for individual clients in the Advanced Settings client tab. This setting is an optional configuration and, when set to zero, uses the same max timeout in the SSO Session Max configuration."

> [§_offline-access, offline token 절 — Revoke Refresh Token 과 offline token 의 상호작용] "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."

> [§_revocation-policy, "Revoking active sessions"] "If your system is compromised, you can revoke all active sessions and access tokens."

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| KC-RTROT-C1 | Realm `Tokens` 탭의 `Revoke Refresh Token` 설정을 **Enabled** 로 하면, Keycloak 은 (refresh token flow 를 수행하는 OIDC client 에 대해) 사용된 refresh token 을 revoke 하고 client 가 사용해야 할 새 토큰을 발급한다 | "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` | Realm Settings → Tokens 탭의 `Revoke Refresh Token` 토글, OIDC client 의 refresh_token grant 흐름 | 이 설정은 본 문서에서 **Enabled/Disabled 이진 토글로만 문서화**됨 — branch 가 언급한 `Refresh Token Max Reuse` (재사용 허용 횟수) 수치 파라미터는 이 자료에 **존재하지 않음**. 즉 "0 = 재사용 불허" 같은 임계값 개념 자체가 이 문서에서 확인되지 않음 |
| KC-RTROT-C2 | Refresh token rotation 하에서는 한 번 사용된 refresh token 은 이후 무효로 간주되며, client 는 항상 가장 최근 refresh 응답의 토큰을 저장해야 한다 — 이전(오래된) refresh token 은 Keycloak 이 더 이상 유효하다고 간주하지 않는다 | "It is possible to specify that the refresh token is considered invalid once it is used. This means that client must always save the refresh token from the last refresh response because older refresh tokens, which were already used, would not be considered valid anymore by Keycloak." | `official-vendor-doc` | 기본 Keycloak refresh token 흐름 (rotation 이 client policy 로 억제되지 않은 경우) — RT 1회 사용 → 그 RT 무효화 라는 골격 | "재사용 시도 시 관련된 다른 토큰들(같은 session 에서 파생된 이전/이후 RT)까지 함께 invalidate 되는 'family invalidate' 메커니즘"에 대한 서술이 **없음**. 이 인용은 "사용된 그 토큰 자체가 무효가 된다"만 말하며, branch D4 가 기술한 "재사용 시 family 전체 invalidate" 는 이 자료로 증명되지 않음 |
| KC-RTROT-C3 | Keycloak 은 refresh token rotation 을 끄는 것도 지원한다 — client policy 실행자(executor) `suppress-refresh-token-rotation` 을 특정 client profile 에 추가하면 해당 client 들에 한해 rotation 이 skip 된다. 이는 FAPI 2 draft/final 사양에서 권장하는 방식이다 | "Keycloak also supports the situation that no refresh token rotation exists. [...] In Keycloak, it is possible to skip refresh token rotation with the use of client policies. You can add executor suppress-refresh-token-rotation to some client profile [...] which means that for those clients the refresh token rotation is going to be skipped." | `official-vendor-doc` | client-policy 수준에서 rotation 을 realm 전역 설정과 별개로 client 단위 override 하는 경우 (FAPI 2 준수 등 특수 목적) | `Revoke Refresh Token` realm 토글과 `suppress-refresh-token-rotation` client policy 가 정확히 어떻게 상호작용하는지(우선순위, 동시 설정 시 동작)는 이 자료에 명시되지 않음 |
| KC-RTROT-C4 | Realm Settings 의 `Sessions`/`Tokens` 탭에는 `Access Token Lifespan`(OIDC access token 수명), `SSO Session Idle`(OIDC client 전용, 비활성 시 user session 무효화), `SSO Session Max`(user session 만료 최대 시간), `Client Session Idle`/`Client Session Max`(client 단위 idle/max — SSO Session Idle/Max 보다 짧아야 하며 override 가능, refresh token 만료·invalidate 시점에 직접 관여)가 정의되어 있다 | "When Keycloak creates an OIDC access token, this value controls the lifetime of the token." / "The maximum time for a client session and before a refresh token expires and invalidates." | `official-vendor-doc` | branch 가 언급한 4개 timeout 설정(Access Token Lifespan, SSO Session Idle/Max, Client Session Idle/Max) 의 존재와 정의 확인 — revoke 즉시성 조정(짧은 Access Token Lifespan)의 근거 | 각 설정의 **권장 수치**(예: "5~15분")는 이 자료에 없음 — branch 결정문의 구체적 숫자는 이 자료로 뒷받침되지 않고 별도 근거 필요 |
| KC-RTROT-C5 | 관리자는 Realm Sessions 메뉴의 `Revocation` 액션으로 특정 시각 이전에 발급된 모든 session/token 을 일괄 무효화하는 정책을 push 할 수 있다 (시스템 침해 대응용). 별도로, `Revoke Refresh Token` 을 활성화하면 offline token 도 1회만 사용 가능해지며 refresh 후 새 offline token 을 저장해야 한다 | "If your system is compromised, you can revoke all active sessions and access tokens." / "If you enable the Revoke Refresh Token option, you can use each offline token once only." | `official-vendor-doc` | 관리자의 bulk revocation(Revocation 정책 push), offline token 에 대한 `Revoke Refresh Token` 의 효과 | `/protocol/openid-connect/revoke` 명시적 revoke 엔드포인트(RFC 7009 스타일)에 대한 서술은 본 페이지에서 확인되지 않음 — branch 가 언급한 revoke endpoint 사용법은 이 자료로 뒷받침되지 않음 |
| KC-RTROT-C6 | (부재 확인 claim) 본 페이지 전체에서 `"Max Reuse"`, `"reuse count"`, `"token family"`, `"family invalid"`, `"reuse detection"` 등의 문자열은 **한 곳도 검색되지 않음** (`grep -i` 결과 0건) | (검증 방법: `grep -ni "max reuse\|maxreuse\|reuse count" / "token family\|family invalid" / "reuse detection\|stolen refresh"` 실행 — 전부 empty) | `needs-confirmation` | branch D1/D4 가 언급하는 "`Refresh Token Max Reuse`" UI 라벨과 "reuse 시 family 전체 invalidate" 라는 정확한 메커니즘 서술의 **부재**를 이 특정 페이지·특정 버전(26.7.0)에 한해 확인 | 이 설정/메커니즘이 Keycloak 에 **존재하지 않는다**는 뜻은 아님 — 다른 문서(Admin Console 자체 UI, 다른 버전, Server Developer Guide, release notes 등)에 있을 수 있음. 단순히 "이 fetched 페이지에는 없다"는 부정적 사실(negative finding)만 확인된 것 |

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `KC-RTROT-C1`: `Revoke Refresh Token` 토글이 실존하며 Enabled 시 "사용된 RT 를 revoke + 새 토큰 발급"한다는 동작
  - `KC-RTROT-C2`: rotation 하에서 RT 는 1회용이며 오래된 RT 는 재유효화되지 않는다는 원칙
  - `KC-RTROT-C3`: rotation 을 client policy 로 끌 수 있다는 대안 존재
  - `KC-RTROT-C4`: Access Token Lifespan / SSO Session Idle·Max / Client Session Idle·Max 설정의 정의와 상호 관계(override, 짧아야 함 등)
  - `KC-RTROT-C5`: admin 수동 bulk revocation 정책, offline token 에 대한 Revoke Refresh Token 의 1회성 효과
  - `KC-RTROT-C6`: 이 페이지·이 버전에 `Refresh Token Max Reuse`/`token family`/`reuse detection` 용어가 부재한다는 부정적 사실
- **이 자료가 증명하지 않는 것**:
  - `Refresh Token Max Reuse` 라는 이름의 수치 파라미터가 Keycloak 25.x/26.x Admin UI 에 실제로 존재하는지 (branch 의 원래 전제 — 이 자료로는 확인 불가, admin UI 실측 또는 다른 버전 문서 필요)
  - RT 재사용 시 "family 전체 invalidate" 되는 정확한 내부 메커니즘 (이 자료는 "사용된 그 토큰이 무효화된다"까지만 말함)
  - `/protocol/openid-connect/revoke` 엔드포인트의 RFC 7009 준수 여부 (본 페이지에 서술 없음)
  - Access Token Lifespan 등 각 timeout 값의 권장 구체 수치
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - Keycloak 25.x/26.x 실제 Admin Console 을 띄워 Realm Settings → Tokens 탭에 `Refresh Token Max Reuse` 라벨이 실존하는지 직접 캡처 확인 (버전별 라벨 변경 가능성 — 이 공식 문서 버전 26.7.0 기준으로는 미확인)
  - RT 재사용 시 실제로 이전에 발급된 RT/AT 세트("family")가 함께 무효화되는지 `docker-compose` 로 Keycloak 을 띄우고 curl 로 재현 실험 (`planned` 등급 유지)

## 메모 / Notes

> 검증되지 않은 내 해석은 여기 두지 않음.

- 이 페이지는 Server Administration Guide 단일 페이지(TOC 포함 전체) — `#_timeouts` 와 `#_refresh_token_rotation` 두 앵커가 branch 의 핵심 질문에 가장 근접.
- `Revoke Refresh Token` 은 realm 전역의 이진 토글이고, `suppress-refresh-token-rotation` 은 client policy 실행자로 이를 client 단위로 무력화하는 별개의 메커니즘 — branch D1 작성 시 두 개념을 혼동하지 않도록 구분 필요.
- branch 가 전제한 `Refresh Token Max Reuse` 필드는 이번 발췌 범위에서 **확인되지 않았다** — 이것이 실제로 Keycloak 에 없는 설정인지, 이 문서 버전에서 누락된 것인지, 또는 admin UI 에는 있지만 Server Administration Guide 텍스트로는 문서화가 안 된 것인지는 이 raw 만으로 판단 불가. branch 의 `UNSUPPORTED_DECISION` 라벨은 이 자료로 해제되지 않고 오히려 "확인 시도했으나 확인 못 함"으로 격상되어야 함.
- 추가로 봐야 할 동일 출처 페이지: Keycloak REST Admin API 문서(구체적 realm representation 필드명 확인용), Keycloak GitHub 소스코드의 `RefreshTokenMaxReuse` 관련 실제 필드/변수명 검색.

## Related / 관련

- 같은 주제 다른 official-doc:
  - [[raw/official-docs/keycloak-securing-apps-overview-official]] — Securing Apps overview (protocol 우선 원칙)
  - [[raw/official-docs/keycloak-oidc-logout-endpoint-official]] — logout endpoint
  - [[raw/official-docs/oauth-v2-1-draft-ietf]] — OAuth 2.1 draft (rotation 권고 배경)
  - [[raw/official-docs/oauth2-pkce-rfc-7636]] — PKCE
- 인용하는 branch:
  - [[raw/branch-notes/feature-keycloak-refresh-token-rotation]]
- 인용한 wiki: (미작성)