donghyeon.kang/llm-wiki

Fork 0

Files

T

DongHyeonka 6c53ded9cb init: llm-wiki-haness 하네스 설계

2026-07-24 14:21:35 +09:00

13 KiB

Raw Blame History

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

title

source_type

url

archive_url

related_branches

related_projects

Keycloak — Client-level PKCE Method Enforcement (Capability Config, "PKCE method")

Layer: raw/official-docs/ — Keycloak Server Administration Guide (latest, version 26.7.0 as served at fetch time) 발췌. Client 단위로 PKCE challenge method 를 강제하는 "PKCE method" 옵션의 정의·선택지·기본 동작.

Parent / 활용 branch

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-keycloak-internal-spa-direct-no-google	D5 (PKCE S256 의무 / Keycloak client 설정에서 PKCE method 강제)의 Keycloak vendor 측 근거 — Admin UI 옵션 이름/위치/선택지별 동작을 명시. `plain` 거부 여부는 부분적으로만 근거함 (아래 Usage Boundaries 참조)
raw/branch-notes/feature-keycloak-pkce-flow-stages	D5 (TODO step 2: "Keycloak client 설정: `Proof Key for Code Exchange Code Challenge Method = S256` 강제") 의 정확한 UI 라벨·위치 근거. 기존 라벨 추정("Proof Key for Code Exchange Code Challenge Method")이 실제로는 "PKCE method" 임을 정정
raw/branch-notes/feature-keycloak-vanilla-js-spa-pkce	vanilla JS SPA client 를 Keycloak 에 등록할 때 client-level PKCE 강제 옵션의 실체 확인 근거

출처 / Source

원본 URL: https://www.keycloak.org/docs/latest/server_admin/index.html#_proof-key-for-code-exchange
아카이브 URL: (미수집)
저자 / 조직: Keycloak project (Red Hat / CNCF 산하 오픈소스 IAM)
발행일: 버전 관리 문서 (latest 채널, 확인 시점 버전 26.7.0 — 페이지 내 version=26.7.0 메타데이터로 확인)
마지막 확인일: 2026-07-17

중요 — 사용자가 제공한 anchor 정정: 입력 URL(#_client_advanced_settings)은 현재 버전(26.7.0) 문서에 존재하지 않는 anchor다. 실제 "Advanced configuration" 섹션의 anchor 는 #con-advanced-settings_server_administration_guide 이며, 정작 PKCE 관련 옵션("PKCE method")은 Advanced configuration 섹션이 아니라 그 앞의 "Basic configuration" → "Capability Config" 하위 섹션(anchor #_proof-key-for-code-exchange)에 위치한다. 최초 WebFetch 시도 2회(주어진 anchor URL, 그리고 anchor 없는 전체 페이지 URL)는 페이지 용량이 커서 모델 요약 과정에서 이 섹션이 누락되는 결과를 반환했다 — 이는 STOP조건3의 "빈 본문/실패"는 아니었고(HTTP 200, 실제 본문 존재), WebFetch 도구의 대용량 페이지 요약 누락이었다. 이에 curl로 원본 HTML을 직접 저장한 뒤 Python으로 태그를 제거해 원문 텍스트를 재구성했고(요약 없음, 발췌 아님 — 전체 절 verbatim 보존), 이 텍스트 파일에 대해 Self-Grep 검증을 수행했다. 임시 파일: /tmp/claude-1000/-home-donghyeon-workspace-ai-tool-llm-wiki-private/3757f6d0-2d79-4e36-b971-598b363e5aaf/scratchpad/source-fetch-20260717172624.txt (원본 HTML 원본: .../scratchpad/kc-server-admin-raw.html, 1,846,056 bytes, curl -sL 로 200 OK 확인).

왜 저장했는지 / Why archived

P2A branch 의 Decision D5("PKCE S256 의무 — Keycloak client 설정에서 PKCE method = S256 강제")가 인용한 기존 claim(PKCE-RFC7636-C3, OA21-C1)은 RFC/OAuth 2.1 표준의 S256 공식과 PKCE 사용 의무만 증명하고, Keycloak이 client 별로 이를 어떻게 노출·강제하는지는 증명하지 않았다(그 raw 문서 자신의 Usage Boundaries가 이를 명시). 본 자료는 그 vendor-side gap을 메우기 위해 Keycloak 공식 Server Admin Guide 에서 "PKCE method" 옵션(빈값/S256/plain 3가지 선택지와 각각의 서술)을 직접 발췌한다.

핵심 인용 / Key quotes (verbatim)

[§Basic configuration → Capability Config → "PKCE method", 2026-07-17] "If an attacker steals an authorization code of a legitimate client, Proof Key for Code Exchange (PKCE) prevents the attacker from receiving the tokens that apply to the code. With this option, you can specify which PKCE challenge method is required for this client."

[§Capability Config → PKCE method → "(blank)"] "Keycloak does not apply PKCE unless the client sends the appropriate PKCE parameters to Keycloak authorization endpoint. So PKCE is still possible to use, but it is not required."

[§Capability Config → PKCE method → "S256"] "Keycloak applies to the client PKCE whose code challenge method is S256."

[§Capability Config → PKCE method → "plain"] "Keycloak applies to the client PKCE whose code challenge method is plain."

[§Advanced configuration → Client Policies → Use-cases, executor 목록] "Enforce Proof Key for Code Exchange (PKCE) is used"

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
KC-PKCE-C1	Keycloak Admin Console 에서 client 단위 PKCE 강제 옵션의 정식 명칭은 "PKCE method" 이며, 이 옵션으로 "which PKCE challenge method is required for this client" 를 지정한다	[§Capability Config, "PKCE method"] "...you can specify which PKCE challenge method is required for this client."	`official-vendor-doc`	Keycloak 26.7.0 (latest 채널) Admin Console UI 의 client Settings 탭 → Capability Config 섹션	이 옵션의 내부 REST 표현/속성명(예: `pkce.code.challenge.method`)이 실제 Keycloak client representation 필드명이라는 것 — 본 페이지엔 이 내부 속성명이 명시되지 않음
KC-PKCE-C2	옵션 값이 "(blank)"(기본/미설정) 이면 Keycloak 은 PKCE 를 강제하지 않는다 — client 가 PKCE 파라미터를 보내면 사용은 가능하지만 필수는 아니다	[§Capability Config → "(blank)"] "Keycloak does not apply PKCE unless the client sends the appropriate PKCE parameters to Keycloak authorization endpoint. So PKCE is still possible to use, but it is not required."	`official-vendor-doc`	옵션 값이 비어 있는(default) client 상태	"(blank)" 가 신규 client 생성 시 실제로 자동 선택되는 값이라는 명시적 문장은 없음(다만 옵션 목록의 첫 항목으로 서술) — 신규 client 생성 시 default 값 확인은 Admin Console 또는 REST API 직접 확인 필요
KC-PKCE-C3	옵션 값이 "S256" 이면 "Keycloak applies to the client PKCE whose code challenge method is S256"	[§Capability Config → "S256"] "Keycloak applies to the client PKCE whose code challenge method is S256."	`official-vendor-doc`	PKCE method = S256 로 설정된 client	`code_challenge_method=plain` 으로 온 authorization request 를 Keycloak 이 거부(reject/invalid_request)한다는 문장이 없다. "applies... PKCE whose code challenge method is S256" 는 강제 적용을 암시하는 서술이지만, 불일치 시의 정확한 동작(에러 코드, HTTP status, silent fallback 여부)은 이 인용에 없음 — D5 의 "plain 금지" 는 이 자료만으로 완전히 증명되지 않음
KC-PKCE-C4	옵션 값이 "plain" 이면 "Keycloak applies to the client PKCE whose code challenge method is plain" — S256 과 대칭적으로 plain 방법도 선택 가능한 옵션으로 명시적으로 존재	[§Capability Config → "plain"] "Keycloak applies to the client PKCE whose code challenge method is plain."	`official-vendor-doc`	PKCE method = plain 로 설정된 client (선택 가능함을 보여줌)	`plain` 자체가 보안상 열등하다는 가치 판단은 본 절에 없음(RFC 7636 별도 근거 필요, 이미 `PKCE-RFC7636-C3` 가 커버)
KC-PKCE-C5	"PKCE method" 드롭다운과 별개로, Client Policies 메커니즘에도 "Enforce Proof Key for Code Exchange (PKCE) is used" 라는 policy executor 가 존재 (FAPI/OAuth 2.1 conformance profile 맥락)	[§Advanced configuration → Client Policies → Use-cases] "Enforce Proof Key for Code Exchange (PKCE) is used"	`official-vendor-doc`	Client Policies 로 PKCE 사용 자체를 강제하려는 realm-level 정책 시나리오	이 executor 가 S256 vs plain 중 어떤 method 까지 강제하는지는 명시되지 않음 — "PKCE is used" 라고만 하고 method 는 미언급. Capability Config 의 per-client "PKCE method" 드롭다운과 이 executor 의 관계(중복/대체 여부)도 본 인용 범위 밖

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- KC-PKCE-C1: client-level PKCE 강제 옵션의 Admin UI 정식 명칭은 "PKCE method" (branch D5/TODO 가 추정한 "Proof Key for Code Exchange Code Challenge Method" 라는 라벨은 부정확 — 정정 필요), Capability Config 섹션(Basic configuration 하위)에 위치.
- KC-PKCE-C2: 옵션을 비워두면(blank) PKCE 는 optional (미강제).
- KC-PKCE-C3/KC-PKCE-C4: S256/plain 두 값 모두 선택 가능한 옵션으로 존재하며, 선택 시 "그 client 에 해당 code challenge method 의 PKCE 를 적용한다"는 서술이 있음.
- KC-PKCE-C5: PKCE 강제를 위한 별도 상위 메커니즘(Client Policies executor)이 존재.
이 자료가 증명하지 않는 것 (중요 — D5 gap 관련):
- Keycloak 이 PKCE method = S256 으로 설정된 client 에 대해 code_challenge_method=plain 요청을 실제로 거부한다는 문장이 이 페이지에 없다. "applies... S256" 이라는 문구는 강제를 암시할 뿐, reject/error response 를 명시적으로 서술하지 않는다. 따라서 D5 의 "plain 금지" 부분은 이 자료만으로 완전히 증명되지 않으며, feature-keycloak-pkce-flow-stages branch의 Claims To Verify 표에 이미 등재된 "Keycloak SPA client 의 PKCE method=S256 토글이 plain 메서드 요청을 거부" 항목은 여전히 needs-confirmation/hands-on 검증 대상으로 남아야 한다.
- 옵션의 내부 REST/attribute 이름(예: pkce.code.challenge.method)은 이 페이지에 등장하지 않는다 — Admin REST API 문서 또는 client representation JSON schema 별도 확인 필요.
- "(blank)" 가 실제 신규 client 생성 시 기본으로 선택되는 값인지에 대한 명시적 진술은 없다(목록상 첫 옵션으로만 서술).
- S256/plain 선택이 realm 전체가 아닌 client 단위로만 적용된다는 것은 문맥상 명확하지만, realm-level 기본값 상속 여부는 다루지 않는다.
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- dev Keycloak 인스턴스에서 client PKCE method = S256 설정 후 code_challenge_method=plain 으로 /auth 요청 → 실제 응답(리다이렉트 에러 파라미터/HTTP status) 확인.
- "PKCE method" 드롭다운과 Client Policies 의 "Enforce PKCE" executor 를 동시에 쓸 때의 상호작용(우선순위/중복) 확인.
- Admin REST API (/admin/realms/{realm}/clients/{id}) 응답에서 이 설정이 어떤 attribute key 로 노출되는지 실제 호출로 확인.

메모 / Notes

사용자가 추정한 UI 라벨 "Proof Key for Code Exchange Code Challenge Method" 는 이번 조사로 부정확함이 확인됨 — 실제 라벨은 짧게 "PKCE method" 이다. branch D5/TODO 항목 표현 정정 시 참고.
WebFetch 도구가 이 큰 페이지(1.8MB HTML)에서 관련 섹션을 2회 연속 놓쳤다 — 페이지 용량이 큰 Keycloak 공식 문서를 다룰 때는 curl 직접 fetch + 태그 스트립 후 grep 검증 경로가 더 안정적일 수 있음(후속 Keycloak 공식 문서 조사 시 재사용 고려).
추가로 봐야 할 동일 출처 페이지: Keycloak Admin REST API 문서(client representation의 attribute 이름 확인용), RFC 7636 §4.1 (code_verifier 문자셋 — 이미 oauth2-pkce-rfc-7636.md 의 Usage Boundaries 에 미인용으로 기록됨).

같은 주제 다른 official-doc:
- raw/official-docs/oauth2-pkce-rfc-7636 — RFC 7636 PKCE 표준 정의 (S256 공식, 위협 모델). 본 자료는 그 vendor 구현측 보완.
- raw/official-docs/oauth-v2-1-draft-ietf — OAuth 2.1 draft, PKCE 전 client 의무화.
- raw/official-docs/keycloak-securing-apps-overview-official — Keycloak Securing Apps overview (본문에 "구체적인 PKCE 설정은 Server Administration Guide 참조"라고 명시했던 바로 그 후속 자료가 본 문서).
인용한 wiki 요약: (미작성)

13 KiB Raw Blame History