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,75 @@
+---
+id: 1a00a640-8987-4075-a9e4-7ec023cdffbb
+kind: REFERENCE
+slug: external-idp-federation-application-boundary
+title: 외부 IdP Federation과 Application 인증 경계
+topic: OAuth/OIDC 인증 경계
+project: KeyCloak Patterns
+status: 게시 전
+version: 9
+studio: "https://hyeonworks.com/studio/documents/1a00a640-8987-4075-a9e4-7ec023cdffbb/edit"
+---
+
+# 외부 IdP Federation과 Application 인증 경계
+
+Google 로그인은 다섯 번째 인증 구조가 아니다. Google에서 브로커의 identity brokering과 local session, authorization code를 지나면 애플리케이션이 고르는 것은 여전히 앞의 네 경계 중 하나다.
+
+## 관계
+
+- **외부 IdP Federation을 별도의 인증 구조로 세지 않는다**
+  이 기준을 프로젝트 결정으로 굳힌 기록이다.
+- **SPA에서 토큰을 직접 관리하면서 드러난 Browser Credential 경계**
+  브로커가 만든 authorization code를 애플리케이션이 받는 흐름이다.
+- **Authorization Code Flow의 Endpoint와 Credential 이동 기준**
+  외부 IdP가 있어도 애플리케이션 쪽 endpoint 이동은 그대로다.
+
+## 목적
+
+외부 IdP를 붙이면서 그것을 애플리케이션 인증 구조로 세게 되면 upstream IdP 경계와 애플리케이션 OAuth 경계를 같은 기준으로 묶게 된다.
+
+Google은 브로커 앞의 upstream identity provider다. 사용자가 브로커 로그인 화면에서 Google을 고르면 브라우저가 upstream authorization을 하게 되고, 브로커가 그 응답을 검증해 local identity와 연결한 뒤 다시 자기가 만든 authorization code를 애플리케이션으로 보내게 된다.
+
+외부 IdP를 추가해도 애플리케이션 쪽에서 브라우저가 token을 받는지, 어느 계층이 API를 호출하는지는 기존 패턴 선택에 따라 결정한다.
+
+## 규칙
+
+### 1. 외부 IdP는 브로커 앞단이고 애플리케이션 경계는 그 뒤다
+
+외부 IdP는 브로커 앞의 provider다. 애플리케이션이 고르는 것은 브로커 뒤의 경계이고, 구조 수를 셀 때 외부 IdP를 목록에 넣으면 성격이 다른 것이 섞인다.
+
+upstream IdP의 identity assertion은 Keycloak이 검증한다. 애플리케이션은 Keycloak이 발급한 authorization code와 token을 사용하고 Resource Server도 Keycloak issuer를 검증하므로 애플리케이션의 OAuth 처리 방식은 기존 패턴을 그대로 따른다.
+
+UI에서 provider를 고르게 하거나 provider별 계정 연결을 다루는 것은 자연스럽다. 다만 Resource Server의 token 검증이나 애플리케이션 인가가 upstream IdP별로 갈리기 시작하면 브로커 경계가 애플리케이션까지 새고 있는지 본다.
+
+외부 IdP의 token을 애플리케이션이 직접 받아 검증하는 경로를 만들면 브로커가 하던 계정 연결과 정책 판단이 함께 빠진다.
+
+### 2. stable identity key는 provider와 upstream subject의 조합이다
+
+email은 바뀔 수 있고 다른 계정과 겹칠 수도 있어서 계정을 잇는 열쇠로 맞지 않는다. 어느 provider의 어느 subject인지를 열쇠로 쓴다. email을 열쇠로 쓰면 사용자가 주소를 바꾼 순간 다른 사람이 된다.
+
+### 3. email 충돌은 별도의 계정 연결 문제로 다룬다
+
+upstream email이 기존 계정과 같다는 이유로 자동 병합하지 않는다. 같은 주소를 쓰는 다른 사람일 수도 있고 주소를 선점한 공격일 수도 있어서, 기존 계정의 소유권을 증명하는 절차를 따로 둔다.
+
+### 4. mock provider로 확인한 범위와 실제 IdP를 구분한다
+
+브로커와 claim mapping 계약까지만 확인했다. 실제 계정과 공개 HTTPS callback, consent 화면, 도메인 정책은 아직 통과해 보지 않았다. 두 범위를 같은 증거로 쓰면 운영에서 처음 보는 실패를 만난다.
+
+## 적용 조건
+
+- 외부 IdP를 붙이며 구조 수를 세려 할 때
+- 계정 연결 규칙을 정할 때
+- 검증 범위를 문서로 적을 때
+- 브로커를 거치는 흐름과 직접 OIDC 흐름을 비교할 때
+
+## 예외
+
+- 애플리케이션이 브로커를 거치지 않고 외부 IdP와 직접 OIDC를 하는 구조라면 그 IdP가 애플리케이션의 issuer가 된다. 그때는 client 종류와 endpoint 기준을 그대로 적용한다.
+- 조직 계정만 쓰고 외부 IdP가 하나뿐이면 브로커를 두지 않는 선택도 있다. 그때는 계정 연결 규칙이 필요하지 않다.
+
+## 예시
+
+- Google 로그인을 추가해도 애플리케이션이 고르는 것은 여전히 네 경계 중 하나다
+- 브로커가 provider alias와 upstream subject로 account identity를 정한다
+- 애플리케이션이 신뢰하는 issuer는 외부 IdP가 아니라 브로커다
+- mock OIDC provider로 확인한 것은 브로커와 claim mapping 계약까지다