--- title: branch / feature-keycloak-patterns (root, 작업 인덱스) source_type: branch-note status: raw id: BR-KEYCLOAK-PATTERNS-OVERVIEW-020 kind: project-work-item project: keycloak-patterns-overview work_item: WI-KEYCLOAK-PATTERNS-OVERVIEW-020 inherits: [DEC-KEYCLOAK-PATTERNS-OVERVIEW-AUTH-TAXONOMY-001@1] refines: [] overrides: [] depends_on: [] contract_packet: 1 branch: feature-keycloak-patterns parent_branch: related_projects: [keycloak-patterns] tags: [branch, keycloak-patterns, oauth2, oidc, auth] created: 2026-05-25 target_merge: status_label: in-progress contract_packet_sha256: 6855baa10b305d5b251f64bfec1f707854488bd72d631b0f9968cfcaaf1f8981 --- # branch: feature-keycloak-patterns (root) > Layer: `raw/branch-notes/` — **작업 진행 인덱스**. 프로젝트 정의·6 패턴 분류·공통 컴포넌트는 [[raw/project-notes/keycloak-patterns-overview]] 참조. > 본 root는 sub-branch 진행 상태와 일정만 추적. > `status_label`: `in-progress` ## 부모 (필수) [[raw/project-notes/keycloak-patterns-overview]] ## 브랜치 계약 패킷 - **생성 시 프로젝트 개정**: `1` - **패킷 스키마**: `contract_packet: 1` - **완료 조건**: project governance hub가 AP1~AP4 taxonomy와 child progress index를 유지한다 ### 상속한 프로젝트 결정 | Decision Ref | Project Summary | Branch Application | Source | |---|---|---|---| | `DEC-KEYCLOAK-PATTERNS-OVERVIEW-AUTH-TAXONOMY-001@1` | canonical 분류축은 AP1~AP4 인증 통합 아키텍처와 cross-cutting 변형이다 | AP1~AP4 taxonomy와 child progress index를 유지하는 governance hub에 적용한다 | [[raw/project-notes/keycloak-patterns-overview]] | ### 브랜치 지역 결정 > 기존 branch-local 결정은 아래 `## Decision Evidence Map`의 D-row가 소유하며 이 packet에서 복제하지 않는다. | Decision ID | Decision | Relation | Supporting Claims | Status | |---|---|---|---|---| ### 선언한 예외 | Override ID | Overrides | Reason | Approval | Status | |---|---|---|---|---| 없음. ## 프로젝트 SSOT - **canonical SSOT**: [[raw/project-notes/keycloak-patterns-overview]] — 프로젝트 정의 / 6 패턴 분류 / 공통 컴포넌트 / 인프라 / 본인 작업 / 트러블슈팅 / 자신 없는 부분 / 진행 단계. - **사용자 본인 인프라 개요**: [[raw/project-notes/project-infra-overview]] (sister project note) ## 목표 본 root branch는 keycloak-patterns 프로젝트의 **작업 진행 인덱스** 역할. 면접에서 "왜 이 배치를 택했나" / "Google 로그인이 붙으면 흐름이 어떻게 바뀌나" / "BFF vs SPA Direct OIDC trade-off는?"에 자신 있게 답할 수 있는 수준의 6 패턴 이해 + P3A 한정 실 구현이 최종 목표 (canonical SSOT 참조). 본 root 자체의 책무: - 6 sub-branch + 27 sub-sub-branch 진행 상태 추적 - 외부 근거 raw 보존 인덱스 - 머지 후 wiki 추출 시 비교 매트릭스 산출 - 이슈: - PR: ## 범위 ### 포함 범위 - (본문 해당 섹션에서 다룬 항목 참조) ### 제외 범위 - (명시 필요) ## 근거 (root는 hub 역할이라 자체 인용은 적고, 개별 결정 근거는 각 sub-branch의 Sources 표 참조) 개별 패턴별 근거는 sub-branch (feature-keycloak-edge-forwardauth-no-google ~ -6) 의 Sources 표에 위임. ## 6 sub-branch + 27 sub-sub-branch 진행 인덱스 > **⚠️ 갱신 (2026-07-14)**: 아래 6패턴 인덱스는 **Phase 0 legacy(배치×federation 축)**. 현 실행계획 SSOT 는 [[raw/project-notes/keycloak-patterns-overview]] 의 **§Branch 분해 / 실행계획(R4)** — 인증 아키텍처 4패턴(AP1~AP4) + 19 Tier-2. 신규 작업은 hub 분해표를 따르며, 아래 슬러그는 hub §2.3 매핑대로 AP 로 re-map 대상. D2(`-{N}-{M}` numbered 명명)는 CLAUDE.md §11 위반으로 폐기(각 sub-sub 는 이미 content-descriptive 슬러그라 실제 영향은 프레이밍뿐). 총 34 branch-notes (root 1 + sub 6 + sub-sub 27). 모두 `documented-only` / `planned` (P3A만 실 구현 대상). ### P1A — Edge Forward Auth (no Google) — [[raw/branch-notes/feature-keycloak-edge-forwardauth-no-google]] - 외부 근거 raw 5개 / sub-sub 4개 - [[raw/branch-notes/feature-keycloak-oauth2-proxy-oidc-flow]] — oauth2-proxy 구성과 OIDC 흐름 - [[raw/branch-notes/feature-keycloak-nginx-auth-request-integration]] — nginx auth_request 통합 (4kb cookie 함정) - [[raw/branch-notes/feature-keycloak-header-spoofing-defense]] — 헤더 spoofing 방어 (NetworkPolicy / SG / mTLS) - [[raw/branch-notes/feature-keycloak-traefik-forwardauth-alternative]] — Traefik ForwardAuth 대안 비교 ### P1B — Edge + Google IdP Brokering — [[raw/branch-notes/feature-keycloak-edge-forwardauth-google-federation]] - 외부 근거 raw 5개 / sub-sub 4개 - [[raw/branch-notes/feature-keycloak-idp-brokering-google-client]] — Keycloak IdP brokering 구성 (Google client 등록) - [[raw/branch-notes/feature-keycloak-first-broker-login-flow]] — First Broker Login Flow (Confirm Link Existing Account) - [[raw/branch-notes/feature-keycloak-google-claim-attribute-mapping]] — Google claim → Keycloak attribute mapping - [[raw/branch-notes/feature-keycloak-account-linking-sub-vs-email]] — Account Linking 보안 (`sub` vs `email`) ### P2A — Internal SPA + Resource Server (no Google) — [[raw/branch-notes/feature-keycloak-internal-spa-direct-no-google]] - 외부 근거 raw 6개 / sub-sub 5개 - [[raw/branch-notes/feature-keycloak-pkce-flow-stages]] — PKCE 4단계 (verifier/challenge/auth/exchange) - [[raw/branch-notes/feature-keycloak-spring-rs-audience-validator]] — Spring Security Resource Server + audience validator - [[raw/branch-notes/feature-keycloak-spa-token-storage-tradeoff]] — Token 저장 위치 trade-off (localStorage/cookie/memory) - [[raw/branch-notes/feature-keycloak-bff-vs-spa-direct]] — BFF 대안 비교 - [[raw/branch-notes/feature-keycloak-refresh-token-rotation]] — Refresh token rotation + revocation ### P2B — Internal + Google federation — [[raw/branch-notes/feature-keycloak-internal-spa-direct-google-federation]] - 외부 근거 raw 4개 / sub-sub 4개 - [[raw/branch-notes/feature-keycloak-federation-spa-zero-change]] — SPA 코드 변경 없음 검증 (P2A → P2B 전환) - [[raw/branch-notes/feature-keycloak-idp-mappers-claim-to-role]] — IdP Mappers (Google claim → Keycloak role) - [[raw/branch-notes/feature-keycloak-three-leg-trust-chain]] — 3-leg trust chain 검증 - [[raw/branch-notes/feature-keycloak-account-linking-spa-ux]] — Account Linking SPA 컨텍스트 ### **P3A — Single EC2 (실 구현 대상)** — [[raw/branch-notes/feature-keycloak-single-ec2-no-google]] - 외부 근거 raw 4개 / sub-sub 6개 (각 sub-sub는 실 구현 plan 포함) - [[raw/branch-notes/feature-keycloak-docker-compose-stack]] — docker-compose 환경 구성 - [[raw/branch-notes/feature-keycloak-realm-client-export]] — Keycloak realm/client 설정 + JSON export - [[raw/branch-notes/feature-keycloak-spring-rs-role-mapping]] — Spring Boot Resource Server + audience validator - [[raw/branch-notes/feature-keycloak-vanilla-js-spa-pkce]] — vanilla JS SPA (Authorization Code + PKCE) - [[raw/branch-notes/feature-keycloak-iss-claim-hostname-mismatch]] — iss claim mismatch 함정 + KC_HOSTNAME 해결 - [[raw/branch-notes/feature-keycloak-refresh-rotation-and-logout]] — refresh token rotation + 로그아웃 흐름 ### P3B — Single EC2 + Google federation — [[raw/branch-notes/feature-keycloak-single-ec2-google-federation]] - 외부 근거 raw 4개 / sub-sub 4개 - [[raw/branch-notes/feature-keycloak-public-domain-tunneling]] — public 도메인 확보 (ngrok / Cloudflare Tunnel) - [[raw/branch-notes/feature-keycloak-reverse-proxy-headers]] — Keycloak reverse proxy 설정 (KC_PROXY_HEADERS + KC_HOSTNAME) - [[raw/branch-notes/feature-keycloak-google-redirect-uri-policy]] — Google OAuth client 등록 + redirect_uri 갱신 - [[raw/branch-notes/feature-keycloak-https-termination-caddy-nginx]] — HTTPS termination (Caddy vs nginx+certbot vs Cloudflare Tunnel) ## TODO - [x] 6 sub-branch 1차 작성 (목표 / 다이어그램 / 토큰 sequence / 장단점) — 등급: `documented-only` - [x] 28 외부 근거 raw 보존 — 등급: `documented-only` - [x] [[raw/project-notes/keycloak-patterns-overview]] 신설 (메인 SSOT, 2026-05-25) — 등급: `documented-only` - [ ] 6 sub-branch 외부 근거 섹션 강화 (채택 결정 / 검토 대안 / 비교 핵심 구조) — 등급: `planned` - [ ] 각 sub-branch 별 sub-sub-branch (세부 학습/구현 단계) 추가 — 등급: `planned` - [ ] P3A 실 구현 (`/home/donghyeon/workspace/keycloak-patterns/`) — 등급: `planned` - [ ] 6 패턴 trade-off 매트릭스 통합 문서 (Phase 4) — 등급: `planned` ## 진행 중 메모 - root branch-note 슬림화: 프로젝트 정의는 [[raw/project-notes/keycloak-patterns-overview]]로 이전 (2026-05-25). root는 작업 인덱스만 유지. - 외부 근거 구조 강화 후속 작업: ca-tmpl branch-notes와 동일하게 "채택 결정 / 검토 대안 / 비교 핵심" 3단 구조로 재작성. - **역사 기록(폐기됨)**: 초기에는 `feature-keycloak-patterns-{N}-{M}` numbered hierarchy를 제안했으나 현 규칙과 충돌해 사용하지 않는다. 현재 규약은 구현 내용을 드러내는 4~8단어 영문 kebab-case slug이며 계층은 `parent_branch`와 `## Parent`로만 표현한다. ## 결정 사항 (decisions) - **D1** 2026-05-25: 프로젝트 정의는 `raw/project-notes/`에, 작업 진행은 `raw/branch-notes/`에. ca-tmpl과 동일 위계. - **D2 (Historical / superseded — DO NOT USE)** 2026-05-25: sub-sub-branch를 `-{N}-{M}` dash-숫자로 명명하자는 초기 결정. 현 `CLAUDE.md` §11과 `rules/naming-conventions.md`에 의해 폐기되었으며, 구현 내용을 드러내는 4~8단어 영문 kebab-case slug가 현행 결정이다. ## 결정-근거 매핑 > 본 root branch 는 hub 역할 — 자체 결정은 **운영 / 조직 규약** 만 다루고, 패턴 채택 결정은 sub-branch 로 위임됨. 따라서 본 hub 의 결정은 외부 raw source 가 아닌 **프로젝트 내부 규약 (CLAUDE.md / rules/) + ca-tmpl 선례** 에 근거함 → 외부 raw claim 측면에서는 모두 UNSUPPORTED_DECISION. | Decision ID | Decision | Supporting Claims | Evidence Strength | Open Risk | |---|---|---|---|---| | D1 | 프로젝트 정의는 `raw/project-notes/`, 작업 진행은 `raw/branch-notes/` 분리 (ca-tmpl 과 동일 위계) | UNSUPPORTED_DECISION (외부 raw source 없음 — 내부 규약 `rules/linking-rules.md` §12 named hub 패턴 + `CLAUDE.md` §2 디렉터리 역할 + ca-tmpl 선례에 근거) | `internal-convention` | 외부 표준 근거 없음 — 다른 wiki / KMS 패턴과 비교 평가 미수행. 단 본 프로젝트 단일 vault 내 일관성은 충분 | | D2 | **RETIRED / superseded** — `-{N}-{M}` numbered hierarchy는 사용하지 않는다. 현행 규약은 구현 내용을 드러내는 4~8단어 영문 kebab-case slug이고 계층은 `parent_branch` + `## Parent`로만 표현한다. | `CLAUDE.md` §11 + `rules/naming-conventions.md` §2.1.2~§2.1.6 | `internal-convention` | 기존 파일·링크에 남은 numbered slug는 별도 migration 계획으로 정리하되 신규 문서에서는 생성 금지 | ## 구현 가이드 > **Trace**: D1(프로젝트 정의와 진행 노트 분리)과 D2(내용 기반 slug + frontmatter 계층)를 따른다. > > - **UNSUPPORTED_IMPL_DECISION**: hub의 수기 인덱스 갱신 방식은 외부 raw source가 정하지 않는 vault 운영 선택이다. 본 hub에는 class/config/API 명세를 두지 않고, child owner의 진행 상태와 링크만 유지한다. - [[raw/branch-notes/feature-keycloak-edge-forwardauth-no-google]] — P1A 작업 묶음 owner; 구현·설정 세부는 child에서만 유지한다. - [[raw/branch-notes/feature-keycloak-edge-forwardauth-google-federation]] — P1B 작업 묶음 owner; 구현·설정 세부는 child에서만 유지한다. - [[raw/branch-notes/feature-keycloak-internal-spa-direct-no-google]] — P2A 작업 묶음 owner; 구현·설정 세부는 child에서만 유지한다. - [[raw/branch-notes/feature-keycloak-internal-spa-direct-google-federation]] — P2B 작업 묶음 owner; 구현·설정 세부는 child에서만 유지한다. - [[raw/branch-notes/feature-keycloak-single-ec2-no-google]] — P3A 구현 owner; hub는 증거 등급과 완료 상태만 반영한다. - [[raw/branch-notes/feature-keycloak-single-ec2-google-federation]] — P3B 문서 작업 owner; hub는 증거 등급과 완료 상태만 반영한다. ## 엣지·실패·의존 - **실패·엣지 경로**: 수기 인덱스가 실제 파일·`parent_branch`와 어긋나면 진행률과 owner 탐색이 stale해진다. 아래 Claims To Verify의 파일·frontmatter 대조를 통과한 뒤에만 개수를 갱신한다. - **다른 계약 의존**: [[raw/project-notes/keycloak-patterns-overview]]가 실행계획과 패턴 분류를 소유한다. 본 hub는 그 내용을 재진술하지 않고 위 child owner 링크와 상태만 소비한다. ## 검증해야 할 주장 > root branch 는 hub 인덱스이므로 자체 verification 보다는 sub-branch 의 결정 / 구현이 정확한지에 대한 메타 검증 항목 위주. | Claim | Why uncertain | How to verify | Status | |---|---|---|---| | 6 sub-branch + 27 sub-sub-branch 진행 인덱스가 실제 파일과 일치 | 본 root 의 인덱스는 수기 유지, drift 가능 | `ls raw/branch-notes/feature-keycloak-*` + `grep parent_branch:` 와 본 §6 sub-branch 인덱스 cross-check | `needs-confirmation` | | 폐기된 numbered slug가 기존 파일·링크에 남아 있는지 | D2는 폐기됐지만 역사적으로 생성된 경로가 있을 수 있어 일괄 rename 시 링크 파손 위험이 있음 | `rules/naming-conventions.md` 기준으로 기존 slug를 inventory하고, 역링크를 포함한 별도 migration plan에서 단계적으로 정리 | `planned` | | P3A 한정 실 구현 → wiki/projects/ 승급 가능한 verified 항목이 실제로 생성됨 | 현재 모두 `documented-only` / `planned` | Phase 3 완료 후 [[raw/branch-notes/feature-keycloak-single-ec2-no-google]] 의 TODO 항목별 `actually-implemented` / `locally-verified` 등급 부여 + 측정 evidence 첨부 | `planned` | | 패턴별 외부 근거 raw 자료가 모두 `## Claims Extracted` + `## Usage Boundaries` 구조를 갖춤 | claim traceability 정책이 2026-05-27 도입 — 기존 raw 는 migration 대상 | `grep -L "## Claims Extracted" raw/official-docs/keycloak*` + `raw/company-tech-blogs/keycloak*` | `needs-confirmation` | ## 마주친 문제 - 아직 없음(문서 단계). ## 묶음 - [[raw/company-tech-blogs/curity-bff-pattern-spa]] - [[raw/company-tech-blogs/keycloak-google-login-codemancers]] - [[raw/official-docs/cloudflare-tunnel-routing-official]] - [[raw/official-docs/google-oauth2-redirect-uri-validation-official]] - [[raw/official-docs/google-openid-connect-oidc]] - [[raw/official-docs/keycloak-first-broker-login-flow]] - [[raw/official-docs/keycloak-first-login-flow]] - [[raw/official-docs/keycloak-getting-started-docker]] - [[raw/official-docs/keycloak-google-idp-setup]] - [[raw/official-docs/keycloak-hostname-configuration]] - [[raw/official-docs/keycloak-identity-brokering-overview-official]] - [[raw/official-docs/keycloak-reverseproxy-official]] - [[raw/official-docs/keycloak-securing-apps-overview-official]] - [[raw/official-docs/keycloak-server-containers-docker]] - [[raw/official-docs/nginx-auth-request-module-official]] - [[raw/official-docs/ngrok-http-tunnel-official]] - [[raw/official-docs/oauth-v2-1-draft-ietf]] - [[raw/official-docs/oauth2-pkce-rfc-7636]] - [[raw/official-docs/oauth2-proxy-keycloak-oidc-provider-official]] - [[raw/official-docs/oauth2-proxy-nginx-integration-official]] - [[raw/official-docs/oauth2-proxy-overview-config-official]] - [[raw/official-docs/oidc-client-ts-library]] - [[raw/official-docs/owasp-html5-storage-xss-spa]] - [[raw/official-docs/spring-security-resource-server-jwt]] - [[raw/official-docs/traefik-forwardauth-middleware-official]] - [[raw/branch-notes/feature-keycloak-account-linking-spa-ux]] - [[raw/branch-notes/feature-keycloak-bff-vs-spa-direct]] - [[raw/branch-notes/feature-keycloak-edge-forwardauth-google-federation]] - [[raw/branch-notes/feature-keycloak-edge-forwardauth-no-google]] - [[raw/branch-notes/feature-keycloak-federation-spa-zero-change]] - [[raw/branch-notes/feature-keycloak-https-termination-caddy-nginx]] - [[raw/branch-notes/feature-keycloak-internal-spa-direct-google-federation]] - [[raw/branch-notes/feature-keycloak-internal-spa-direct-no-google]] - [[raw/branch-notes/feature-keycloak-pkce-flow-stages]] - [[raw/branch-notes/feature-keycloak-public-domain-tunneling]] - [[raw/branch-notes/feature-keycloak-reverse-proxy-headers]] - [[raw/branch-notes/feature-keycloak-single-ec2-google-federation]] - [[raw/branch-notes/feature-keycloak-single-ec2-no-google]] > 본 root는 6 sub-branch hub. 위 "6 sub-branch + 27 sub-sub-branch 진행 인덱스" 섹션과 중복 정보이나, `templates/linking-rules.md` §4 양방향 작성 패턴에 따라 카테고리별 명시. ### Sub-branches (6 패턴별 hub) - [[raw/branch-notes/feature-keycloak-edge-forwardauth-no-google]] — P1A Edge / Ingress (no Google) - [[raw/branch-notes/feature-keycloak-edge-forwardauth-google-federation]] — P1B Edge / Ingress + Google federation - [[raw/branch-notes/feature-keycloak-internal-spa-direct-no-google]] — P2A Cluster-internal SPA-direct (no Google) - [[raw/branch-notes/feature-keycloak-internal-spa-direct-google-federation]] — P2B Cluster-internal + Google federation - [[raw/branch-notes/feature-keycloak-single-ec2-no-google]] — P3A Single EC2 (no Google) **— vanilla JS 실 구현 대상** - [[raw/branch-notes/feature-keycloak-single-ec2-google-federation]] — P3B Single EC2 + Google federation ### 근거 자료 - (패턴별 official-docs / company-tech-blogs 는 sub-branch 의 Sources 표에서 cited) ### 오류 기록 - (없음 — Phase 3 P3A 실 구현 진입 시 발생 예상) ### 면접 준비 - (없음 — 패턴별 면접 후보는 sub-branch Cluster의 Interview prep 항목 참조) ### 강의 - (없음) ### Blog drafts / job-posting tie-ins - (없음) ## 관련 일일 노트 ## 완료 후 정리 - PR 링크: - 리뷰 메모: - 머지 결과 / 배포 환경: P3A 한정 로컬 검증 예정 - **wiki 추출 대상** (verified만, `wiki/projects/`로만 추출): - `actually-implemented` 항목: (Phase 3 완료 후 채움) - `locally-verified` 항목: (Phase 3 완료 후 채움) - `prod-verified` 항목: (없음, prod 배포 out of scope) - **추출하지 않을 항목** (planned / documented-only / abandoned): P1A/P1B/P2A/P2B/P3B 5개 패턴은 문서까지만.