# 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`로 추적한다.