---
title: Keycloak 25.0.0 released — Hostname v2 옵션 도입 공지
source_type: official-doc
url: https://www.keycloak.org/2024/06/keycloak-2500-released
archive_url:
related_branches: [feature-keycloak-iss-claim-hostname-mismatch]
related_projects: [keycloak-patterns]
tags: [official-doc, keycloak-patterns, auth, keycloak, kc-hostname]
created: 2026-07-17
---

# Keycloak 25.0.0 released — Hostname v2 옵션 도입 공지

> Layer: `raw/official-docs/` — Keycloak 공식 블로그의 25.0.0 릴리즈 공지 중 "New Hostname options" 섹션 발췌.
> 본 템플릿은 `raw/official-docs/` 와 `raw/company-tech-blogs/` 두 폴더가 공유.
> 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 `source-summary-template` 형식으로 별도 작성. 원본은 raw에 영구 보관.

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

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-keycloak-iss-claim-hostname-mismatch]] | branch 노트가 출처 없이 적은 메모 "Keycloak 26.x 에서 `KC_HOSTNAME_*` 옵션 명칭이 자주 바뀜"의 진위 판정 — hostname v2 가 언제(25.0), 왜 도입됐고 기존 v1 옵션이 deprecated 됐는지의 1차 공식 근거 |

## 출처 / Source

- 원본 URL: https://www.keycloak.org/2024/06/keycloak-2500-released
- 아카이브 URL: (미수집)
- 저자 / 조직: Keycloak (Red Hat) — 공식 블로그
- 발행일: 2024-06-10 (페이지 내 "June 10 2024" 표기)
- 마지막 확인일: 2026-07-17

## 왜 저장했는지 / Why archived

`feature-keycloak-iss-claim-hostname-mismatch` branch 본문의 "마주친 문제" 섹션에 출처 없이 적힌 "Keycloak 26.x에서 `KC_HOSTNAME_*` 옵션 명칭이 자주 바뀜"이라는 메모의 진위를 판정하기 위해 저장. 본 공지는 hostname 옵션 개편이 **24→25 사이 1회의 대개편**(v1→v2)이었음을 1차 공식 소스로 확인해준다.

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

> [Highlights § "New Hostname options"] "In response to the complexity and lack of intuitiveness experienced with previous hostname configuration settings, we are proud to introduce Hostname v2 options."

> [Highlights § "New Hostname options"] "Be aware that even the behavior behind these options has changed and requires your attention - if you are dealing with custom hostname settings."

> [Highlights § "New Hostname options"] "Hostname v2 options are supported by default, as the old hostname options are deprecated and will be removed in the following releases."

> [Highlights § "New Hostname options"] "You should migrate to them as soon as possible."

> [Highlights § "New Hostname options"] "New options are activated by default, so Keycloak will not recognize the old ones."

## Claims Extracted / 추출된 주장

> 이 자료가 **직접 말하는 것만** claim 으로 분리한다. 내 프로젝트에 적용한 결론은 여기 쓰지 않는다.

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| KC-2500-C1 | Keycloak 은 25.0.0 릴리즈에서 기존 hostname 설정의 복잡성·비직관성 문제 때문에 새로운 Hostname v2 옵션을 도입했다 | "In response to the complexity and lack of intuitiveness experienced with previous hostname configuration settings, we are proud to introduce Hostname v2 options." | `official-vendor-doc` | Keycloak 25.0.0 릴리즈 시점의 hostname 옵션 개편 동기 | v2 옵션의 구체적인 개별 옵션명·boolean 극성 등 세부 스펙 |
| KC-2500-C2 | v2 옵션은 기존 옵션과 **동작(behavior) 자체가 달라졌으며**, custom hostname 설정을 쓰는 사용자는 이를 주의해야 한다 | "Be aware that even the behavior behind these options has changed and requires your attention - if you are dealing with custom hostname settings." | `official-vendor-doc` | custom hostname 설정을 사용 중인 모든 Keycloak 25.0.0 업그레이드 사용자 | v1→v2 옵션별 1:1 대응표나 정확히 어떤 동작이 어떻게 바뀌었는지의 세부 내용 (hostname guide 원문 소관) |
| KC-2500-C3 | v2 옵션이 25.0.0 부터 기본값으로 활성화되며, 기존(v1) hostname 옵션은 deprecated 되어 향후 릴리즈에서 제거될 예정이다 | "Hostname v2 options are supported by default, as the old hostname options are deprecated and will be removed in the following releases." | `official-vendor-doc` | Keycloak 25.0.0 이후 버전의 hostname 옵션 기본 활성 상태 및 v1 옵션의 deprecation 계획 | v1 옵션이 실제로 제거된 정확한 버전(예: 26.0 여부) — 이는 26.x 릴리즈 노트 소관 |
| KC-2500-C4 | 사용자는 v1 → v2 로 가능한 빨리 마이그레이션해야 하며, 새 옵션이 기본 활성화되어 있어 Keycloak 이 옛 옵션을 인식하지 않는다 | "You should migrate to them as soon as possible." / "New options are activated by default, so Keycloak will not recognize the old ones." | `official-vendor-doc` | 25.0.0 업그레이드 시 v1 옵션만 설정해둔 환경의 즉시 마이그레이션 필요성 | v1 옵션을 켜서 구버전 동작으로 되돌리는 방법이 존재하는지 여부(Migration guide 별도 소관) |

### Strength 허용값

- `official-standard` — RFC, 표준 사양, 언어/프로토콜 표준
- `official-vendor-doc` — Spring, Keycloak, AWS, Google 등 공식 벤더 문서
- `official-reference` — 공식 reference/API 문서
- `company-case-study` — 대기업/실무 기술 블로그의 특정 사례
- `engineering-blog` — 개인/팀 블로그의 엔지니어링 해설
- `tutorial` — 튜토리얼/가이드. 일반화 금지
- `needs-confirmation` — 원문만으로는 적용 판단 불가

## Usage Boundaries / 적용 경계

- 이 자료가 직접 증명하는 것:
  - `KC-2500-C1`~`KC-2500-C4`: Hostname v2 옵션이 **Keycloak 25.0.0 릴리즈 시점(2024-06-10)에 도입**됐고, 도입 동기가 기존 설정의 복잡성/비직관성이었으며, 기존 v1 옵션은 deprecated 되어 제거 예정이라는 것.
- 이 자료가 증명하지 않는 것:
  - v1→v2 옵션별 1:1 대응표(예: `hostname-strict-backchannel` → `hostname-backchannel-dynamic` 의 boolean 극성 반전 여부) — 이는 각 버전의 hostname guide 원문 소관.
  - 26.x 시점의 최종 옵션 집합(v1 옵션이 실제로 제거되었는지, 새 옵션이 26.x 안에서 추가로 rename 됐는지) — 이는 26.0 릴리즈 노트 + 현행 hostname guide 소관.
  - branch 메모의 "Keycloak 26.x에서 `KC_HOSTNAME_*` 옵션 명칭이 **자주** 바뀜"이라는 프레이밍 — 본 자료는 **24→25 사이 1회의 대개편**(v1→v2, 2024-06-10)만 증명한다. "자주"라는 빈도 주장은 이 자료가 지지하지 않는다.
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - 실제 사용 중인 Keycloak 버전(26.x 추정)에서 v1 옵션이 여전히 인식되는지, 아니면 완전히 제거되었는지 — 현행 hostname guide([[raw/official-docs/keycloak-hostname-configuration]]) 재확인 필요.

## 메모 / Notes

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

- branch 메모 판정 결과 (참고용, 인용 아님): 이 자료는 branch 노트의 "옵션 명칭이 자주 바뀜"이라는 메모를 **부분 confirm / 프레이밍은 refute** 한다 — hostname 옵션 개편이 실재하는 사건인 것은 맞지만(v1→v2, 25.0.0), 이 자료 자체는 "24→25→26 여러 번에 걸쳐 자주" 바뀌었다는 빈도를 증명하지 않는다. "자주"를 확인하려면 25.x/26.x 각 릴리즈 노트를 추가로 대조해야 한다 (`needs-confirmation`으로 유지).
- 추가로 봐야 할 동일 출처 페이지: Keycloak 26.0.0 릴리즈 노트 (v1 옵션 실제 제거 여부 확인용), 현행 hostname guide의 Migration guide 섹션.

## Related / 관련

- 같은 주제 다른 official-doc: [[raw/official-docs/keycloak-hostname-configuration]] — 현행(rolling) v2 hostname guide 본문. 옵션별 세부 스펙은 이쪽이 1차 근거.
- 이 자료를 인용한 wiki 요약: (아직 생성되지 않음)