docs: compare four authentication patterns

docs/four-pattern-tradeoff-matrix.md

@@ -0,0 +1,37 @@
+# Four Keycloak integration patterns
+
+| 축 | AP1 SPA direct | AP2 token mediator | AP3 BFF | AP4 edge auth |
+|---|---|---|---|---|
+| OAuth client | public | confidential | confidential | confidential proxy |
+| browser 보유물 | access/refresh token | 짧은 handoff code 또는 app token | HttpOnly session cookie | proxy session cookie |
+| OAuth code 교환 | browser + PKCE | mediator backend | BFF | oauth2-proxy |
+| API bearer 검증 | Spring resource server | mediator/downstream API | BFF 내부 또는 downstream | edge가 인증 후 trusted header |
+| server session | 없음 | handoff 상태만 짧게 | 필수 | proxy cookie/session |
+| XSS token 탈취면 | 가장 큼 | 축소 | browser token 제거 | browser token 제거 |
+| CSRF 주의 | token endpoint/refresh 설계 | app cookie 사용 시 | 필수 방어 | proxy cookie 사용 시 |
+| 수평 확장 상태 | 단순 | handoff store 공유 가능 | session store 필요 | proxy 설정에 따름 |
+| 주 학습 포인트 | PKCE/JWT/RS | token 경계·one-time handoff | oauth2Login/session/CSRF | auth_request/header trust |
+
+## 선택 기준
+
+- 브라우저에서 OAuth와 token 수명주기를 직접 학습하려면 AP1.
+- 브라우저에 upstream token을 주지 않되 API 호출은 bearer 중심으로 유지하려면
+  AP2.
+- token을 browser에서 완전히 제거하고 애플리케이션 단위 인가·세션을
+  중앙화하려면 AP3.
+- 기존 upstream을 수정하기 어렵고 경계에서 일괄 인증하려면 AP4.
+
+Google federation은 다섯 번째 인증 패턴이 아니다. 네 패턴 모두 최종적으로
+Keycloak token/session을 소비하며, Google은 Keycloak 앞의 upstream IdP
+hop으로 추가된다.
+
+## 이 repository의 실행 증거
+
+- AP1: PKCE SPA, issuer/audience, token storage, refresh/logout 검증
+- AP2: confidential client와 one-time access handoff 검증
+- AP3: `oauth2Login` session과 CSRF/SameSite 검증
+- AP4: oauth2-proxy, nginx `auth_request`, spoofed header 제거 검증
+- 공통: local mock Google brokering, First Broker Login, claim/role mapping 검증
+
+각 근거 브랜치와 병합 여부는 `keycloak-branch-manifest.tsv` 및
+`audit-keycloak-branches.sh`로 추적한다.