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,50 @@
+---
+id: 5f4b6000-cb78-400c-bf6e-a25632a4bb40
+kind: PROJECT_DECISION
+slug: patterns-are-not-a-maturity-ladder
+title: 인증 구조를 보안 성숙도 단계로 취급하지 않는다
+topic: OAuth/OIDC 인증 경계
+project: KeyCloak Patterns
+status: 게시 전
+version: 11
+decisionStatus: ADOPTED
+decidedOn: 2026-08-24
+studio: "https://hyeonworks.com/studio/documents/5f4b6000-cb78-400c-bf6e-a25632a4bb40/edit"
+---
+
+# 인증 구조를 보안 성숙도 단계로 취급하지 않는다
+
+SPA, Mediator, BFF, Forward-Auth는 credential을 처리하는 주체와 API 호출 경로가 서로 다르다. 번호나 브라우저 token 노출 여부를 보안 등급으로 사용하지 않고 각각 별도의 아키텍처 패턴으로 취급한다.
+
+## 근거
+
+- **SPA에서 토큰을 직접 관리하면서 드러난 Browser Credential 경계**
+  브라우저가 code 교환, token 보관, API 호출을 직접 수행한다.
+- **Mediator가 Refresh Token을 관리하고 Access Token을 Browser에 전달하는 구조**
+  mediator가 code 교환과 refresh token 보관을 담당하고 브라우저가 access token으로 API를 직접 호출한다.
+- **BFF에서 OAuth Token을 관리할 때 Session과 CSRF를 처리한 과정**
+  BFF가 token과 session을 server-side에서 관리하고 Resource Server를 호출한다.
+- **Forward-Auth에서 Client가 보낸 Identity Header를 신뢰하면 안 되는 이유**
+  oauth2-proxy가 인증을 처리하고 upstream에는 identity header를 전달한다.
+- **OAuth/OIDC 인증 패턴 선택 기준**
+  이 결정을 적용하는 선택 기준이다.
+
+## 결정문
+
+SPA에서 Mediator, BFF, OAuth2-Proxy로 가는 순서를 낮은 보안에서 높은 보안으로 가는 단계로 모델링하지 않는다.
+
+네 구조는 credential과 인증 상태를 처리하는 주체가 서로 다른 별개의 아키텍처 패턴으로 취급한다.
+
+## 판단 이유
+
+BFF는 브라우저 token을 없애지만 server session과 CSRF, 공유 저장소를 만든다. Forward-Auth는 애플리케이션의 token custody를 줄이지만 edge 헤더 신뢰와 network 경계를 만든다. 뒤 구조가 앞 구조의 문제를 없애는 것이 아니라 다른 곳에 다른 요구를 만든다.
+
+네 구조의 차이는 code를 교환하는 주체, token 저장 방식, API 호출 주체, 보호 자원이 신뢰하는 credential에서 확인됐다. 이 차이를 보안 성숙도 순서로 환산하지 않는다.
+
+성숙도 모델로 두면 「일단 제일 뒤 구조로 가자」는 판단이 나온다. backend 직접 경로를 닫을 수 없는 환경에서 edge에 인증을 맡기면 upstream이 헤더 하나로 사용자를 판단하는데 그 헤더를 누구나 만들어 보낼 수 있다. 그런 환경에서는 브라우저가 token을 직접 들고 서명을 검증받는 구조가 낫다.
+
+## 영향
+
+- 패턴을 비교할 때는 적용 조건과 운영해야 할 상태, 신뢰 경계, 장애 지점을 함께 적는다. 브라우저 token 노출 여부 하나만으로 순서를 매기지 않는다.
+- 구조를 고를 때 번호가 아니라 code 교환·token 보관·API 호출의 배치를 먼저 답한다. 뒤 구조에서 앞 구조로 되돌아가는 선택도 후퇴가 아니라 credential 계약의 변경으로 적는다.
+- 구조 이름만으로 운영 속성을 추정하지 않는다. 공유 저장소와 장애 복구, secret 교체는 매번 따로 확인한다.