refactor: 문서 개선 중

2026-09-21 14:30:55 +09:00
parent c93cdea150
commit 805a18f486
1497 changed files with 525837 additions and 59152 deletions
@@ -0,0 +1,55 @@
+---
+id: 19b55c39-c583-4161-9775-df954280a568
+kind: PROJECT_DECISION
+slug: bff-owns-token-when-browser-must-not
+title: BFF가 OAuth Token을 관리하는 조건
+topic: OAuth/OIDC 인증 경계
+project: KeyCloak Patterns
+status: 게시 전
+version: 11
+decisionStatus: PROPOSED
+studio: "https://hyeonworks.com/studio/documents/19b55c39-c583-4161-9775-df954280a568/edit"
+---
+
+# BFF가 OAuth Token을 관리하는 조건
+
+애플리케이션이 API 조합과 인가를 직접 처리하면서 브라우저에는 OAuth token을 전달하지 않아야 한다면 BFF가 authorization code 교환, token 보관, downstream 호출을 담당한다. 이 결정은 아직 프로젝트 기본값으로 채택하지 않아 `PROPOSED` 상태로 둔다.
+
+## 근거
+
+- **BFF에서 OAuth Token을 관리할 때 Session과 CSRF를 처리한 과정**
+  이 결정이 가리키는 구조를 실제로 실행해 본 기록이다.
+- **BFF 인증 구조 설계 기준**
+  이 결정이 PROPOSED인 동안의 실제 적용 기준이다.
+- **OAuth/OIDC 인증 패턴 선택 기준**
+  이 결정을 적용할 조건과 피해야 할 조건이 여기 있다.
+- **Mediator가 Refresh Token을 관리하고 Access Token을 Browser에 전달하는 구조**
+  access token이 브라우저로 나가 이 요구를 만족하지 못한 경우다.
+
+## 결정문
+
+브라우저에 OAuth token을 노출하지 않으면서 애플리케이션이 Resource Server 호출을 중계하고 조합해야 하는 경우, BFF가 authorization code 교환과 token 보관, downstream API 호출을 소유한다.
+
+브라우저에는 애플리케이션 session만 제공한다.
+
+## 판단 이유
+
+브라우저에 OAuth token을 전달하지 않으려면 server가 authorization code를 교환하고 access token을 사용해 downstream API를 호출해야 한다.
+
+Mediator 구조에서는 브라우저가 Resource Server를 직접 호출하므로 access token을 `/token/access` 응답으로 전달한다. 따라서 브라우저에 OAuth token을 제공하지 않는다는 요구에는 맞지 않는다.
+
+Forward-Auth 구조도 브라우저에 OAuth token을 전달하지 않을 수 있지만 upstream은 JWT를 직접 검증하지 않고 edge가 제공한 identity header를 사용한다. 애플리케이션이 access token으로 여러 Resource Server를 직접 호출하거나 사용자별 API 조합을 처리해야 한다면 BFF 쪽이 요구에 더 잘 맞는다.
+
+따라서 브라우저에 OAuth token을 전달하지 않는 조건만으로 BFF를 선택하지는 않는다. 애플리케이션이 downstream API 호출과 조합을 직접 맡아야 하는지도 함께 본다.
+
+다만 상태를 ADOPTED로 올리지는 않는다. 지금 자료는 네 구조를 나란히 실행한 비교 실험이고 이 프로젝트가 BFF를 기본값으로 고른 기록이 없기 때문이다. 기본값으로 고른 시점과 그 근거가 생기면 그때 올리게 되고, 그 전까지 실제 적용 기준은 「BFF 인증 구조 설계 기준」 Reference다.
+
+## 영향
+
+- BFF가 로그인 상태와 token을 가진 보안 구성요소가 되어서 단순 proxy로 취급할 수 없게 된다.
+- 상태 변경 요청마다 CSRF 검증이 필요해지고, 노출 값과 제출 값이 다를 수 있어서 클라이언트 코드도 그 구분을 알아야 한다.
+- 재시작과 replica 이동을 견딜 공유 저장소와 저장 token 암호화, 암호화 key 교체를 설계해야 하는데 아직 정하지 않은 문제로 남아 있다.
+- logout이 애플리케이션 session과 authorized client를 함께 지워야 하는데, 열쇠가 달라서 한 번의 삭제로 두 상태가 함께 지워지지 않는다.
+- 모든 UI 요청이 BFF를 지나게 되어서 지연과 단일 장애 지점을 준비해야 한다.
+- 브라우저에서 token을 없애도 XSS가 무해해지지 않고, same-origin script는 피해자 session으로 BFF를 그대로 부를 수 있다.
+- 이 결정이 PROPOSED인 동안은 「BFF 인증 구조 설계 기준」 Reference가 실제 적용 기준이다.