keycloak-pattern/docs/ap3-bff-boundary.md

AP3 · Backend-for-Frontend

요청과 token 경계

1. 브라우저는 BFF의 /oauth2/authorization/keycloak로 로그인을 시작합니다.
2. Spring oauth2Login은 PKCE S256 authorization code flow를 수행합니다.
3. BFF가 client secret으로 code를 교환하고 access/refresh token을 서버의 OAuth2AuthorizedClientService에 보관합니다.
4. 브라우저에는 OAuth token 대신 HttpOnly AP3_SESSION 식별자만 남습니다.
5. 브라우저가 /bff/api/me를 cookie로 호출하면 BFF가 access token을 Authorization: Bearer로 붙여 Resource Server에 fan-out합니다.

Resource Server는 aud=keycloak-pattern-api를 검증합니다. 브라우저에서는 8081로 직접 요청하거나 Keycloak token endpoint를 호출하지 않습니다.

학습용 구성은 단일 인스턴스 메모리에 session과 authorized client를 보관합니다. BFF를 재시작하면 세션이 사라집니다. 다중 인스턴스 운영에서는 Spring Session/Redis 같은 공유 저장소와 저장 token 암호화 정책이 필요합니다.

방어 전 CSRF 재현

이 feature 브랜치에서는 다음 CSRF 방어 feature와 비교하기 위해 CSRF를 의도적으로 끕니다. 다른 origin의 자동 제출 form이 브라우저 cookie를 자동으로 포함해 /bff/api/preferences 상태를 바꾸는 것을 E2E에서 재현합니다.

이 취약 상태는 feature/keycloak-bff-csrf-samesite-defense에서 Spring CSRF token과 명시적 SameSite=Lax를 적용해 차단합니다.