From 41f05494357ec6283cf3323a967e83c2d7cc6079 Mon Sep 17 00:00:00 2001 From: Lectom C Han Date: Tue, 27 Jan 2026 17:59:14 +0900 Subject: [PATCH] =?UTF-8?q?wiki=EB=A1=9C=20=EC=A0=95=EB=A6=AC=ED=95=9C=20?= =?UTF-8?q?=EB=AC=B8=EC=84=9C=EB=8A=94=20=EC=82=AD=EC=A0=9C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/idp_policy.md | 27 ----------------- docs/shadowing_policy.md | 64 ---------------------------------------- 2 files changed, 91 deletions(-) delete mode 100644 docs/idp_policy.md delete mode 100644 docs/shadowing_policy.md diff --git a/docs/idp_policy.md b/docs/idp_policy.md deleted file mode 100644 index 71544392..00000000 --- a/docs/idp_policy.md +++ /dev/null @@ -1,27 +0,0 @@ -# IDP Abstraction & Perfect Wrapping Policy - -## 1. 핵심 원칙 (Core Principles) - -**"사용자와 클라이언트 개발자는 IDP가 무엇인지 알 수도 없고, 알아서도 안 된다."** - -Baron SSO의 가장 중요한 아키텍처 원칙은 **IDP Agnostic(IDP 불가지론)**입니다. 현재 Descope를 사용하더라도, 내일 당장 Hydra, Authentik, Keycloak 또는 자체 구축 인증 서버로 변경하더라도 **Frontend, Client App, 그리고 최종 사용자에게는 단 1줄의 코드 변경이나 경험의 변화가 없어야 합니다.** - -## 2. 세부 지침 (Guidelines) - -### 2.1. Frontend & Client Side -- **No Vendor SDK**: 프론트엔드 코드(User App, Admin Front)에서 `descope-sdk` 등 특정 벤더의 SDK를 직접 import하여 비즈니스 로직에 사용하는 것을 금지합니다. -- **Unified Interface**: 모든 인증 요청은 Baron SSO Backend API (`/api/v1/auth/*`)를 통해서만 수행합니다. -- **Response Format**: 클라이언트가 수신하는 토큰 및 사용자 정보는 Baron SSO가 정의한 표준 스키마(`BrokerUser`)여야 하며, IDP의 Raw Data가 노출되어서는 안 됩니다. - -### 2.2. Backend Side -- **Provider Pattern**: 모든 IDP 관련 로직은 `interface IDPProvider` 뒤에 숨겨야 합니다. 핸들러(Handler) 계층은 구체적인 구현체(DescopeService 등)를 알지 못해야 합니다. -- **Error Mapping**: IDP에서 발생한 에러(예: `E062907`)는 반드시 Baron SSO의 표준 에러(예: `AUTH_PROVIDER_ERROR`)로 변환되어 클라이언트에 전달되어야 합니다. -- **Configuration Isolation**: IDP 설정(Project ID, API Key)은 환경 변수와 팩토리 내부로 격리하며, 비즈니스 로직에 하드코딩하지 않습니다. - -### 2.3. OIDC/OAuth2 Compliance -- 외부 서비스(RP) 연동 시, Baron SSO 자체가 OIDC Provider로 동작해야 합니다. -- RP는 `Issuer`를 Baron SSO의 URL로 설정하며, 원천 IDP의 URL을 바라보지 않습니다. - -## 3. 마이그레이션 보장 (Migration Guarantee) -이 정책의 최종 목표는 **"IDP 교체 비용을 0에 수렴하게 만드는 것"**입니다. -IDP 변경 시 백엔드의 `IDPProvider` 구현체만 교체하면, 데이터 마이그레이션을 제외한 모든 서비스가 중단 없이 동작해야 합니다. diff --git a/docs/shadowing_policy.md b/docs/shadowing_policy.md deleted file mode 100644 index 4922cbe1..00000000 --- a/docs/shadowing_policy.md +++ /dev/null @@ -1,64 +0,0 @@ -# Shadow Account Policy (Identity Sovereignty) - -## 1. 개요 (Overview) -Baron SSO는 외부 IDP(Descope 등)에 의존하지 않고, **식별자 주권(Identity Sovereignty)**을 갖기 위해 **Shadow Account (그림자 계정)** 모델을 채택합니다. -외부 IDP는 단지 "인증 수단"일 뿐이며, 서비스 내부의 모든 비즈니스 로직, 로그, RP 연동은 Baron SSO가 발급한 고유 식별자(`Baron ID`)를 기준으로 수행됩니다. - -## 2. 식별자 정책 (Identifier Policy) - -### 2.1. Baron ID (Internal User ID) -- **Format**: **UUID v7** (Time-ordered 128-bit) -- **특징**: 생성 시간 순 정렬 가능, DB 인덱싱 효율 최적화, 외부 시스템 충돌 없음. -- **용도**: `users` 테이블 PK, `audit_logs`의 Actor ID, RP에 전달되는 `sub` 값. -- **원칙**: **불변(Immutable)**. 사용자가 이메일이나 연동 IDP를 변경해도 Baron ID는 변하지 않아야 합니다. - -### 2.2. Audit Log ID -- **Format**: **Snowflake** (64-bit Integer) -- **용도**: 감사 로그의 Primary Key. -- **이유**: 초당 대량으로 발생하는 로그 데이터의 적재 성능과 ClickHouse 압축 효율을 위해 정수형 ID 사용. - -## 3. 데이터 모델 (Shadow Schema) - -### 3.1. Users Table (Core) -서비스가 바라보는 사용자의 실체입니다. -```sql -CREATE TABLE users ( - id UUID PRIMARY KEY, -- Baron ID (UUID v7) - email VARCHAR(255), -- 검색 및 알림용 (Unique X, 여러 계정 가능성) - name VARCHAR(100), - status VARCHAR(20), -- 'active', 'blocked' - created_at TIMESTAMPTZ, - last_login_at TIMESTAMPTZ -); -``` - -### 3.2. Federated Identities Table (Mapping) -외부 IDP 계정과 Baron 계정을 연결하는 매핑 테이블입니다. N:1 매핑이 가능합니다. -```sql -CREATE TABLE federated_identities ( - provider VARCHAR(50), -- 'descope', 'google', 'legacy_db' - provider_sub VARCHAR(255), -- IDP의 원천 User ID - user_id UUID REFERENCES users(id), - created_at TIMESTAMPTZ, - PRIMARY KEY (provider, provider_sub) -); -``` - -## 4. 동기화 및 로그인 흐름 (Sync Flow) - -1. **인증 성공**: 백엔드가 IDP(Descope) 토큰을 검증하고 `Provider Sub`(예: `U12345`)를 획득. -2. **조회 (Lookup)**: `federated_identities` 테이블에서 `(provider='descope', provider_sub='U12345')` 조회. -3. **분기 처리**: - - **Case A (기존 회원)**: 매핑된 `user_id` 획득. `users` 테이블의 정보(이메일, 이름)를 IDP 토큰 정보로 **업데이트(Sync)**. - - **Case B (신규 회원)**: 새로운 `UUID v7` 생성 -> `users` Insert -> `federated_identities` Insert. -4. **세션 발급**: Baron ID(`user_id`)를 Payload로 담은 Baron 자체 세션/토큰을 발급하여 클라이언트에 전달. - -## 5. IDP 마이그레이션 전략 (Migration Strategy) - -### 5.1. 식별자 유지 -IDP가 `Descope`에서 `Keycloak`으로 바뀌더라도, 백엔드는 새로운 IDP의 `sub`를 기존 사용자의 `Baron ID`와 매핑(`federated_identities` 추가)하기만 하면 됩니다. RP와 클라이언트는 아무런 변화를 감지하지 못합니다. - -### 5.2. 비밀번호 처리 (Password Handling) -- 해시된 비밀번호는 이관하지 않습니다 (불가능/비효율). -- **Magic Link / Passwordless 우선**: 사용자는 비밀번호 입력 없이 계속 이용 가능. -- **재설정 유도**: 비밀번호 사용 필수 시, "보안 정책 변경" 안내와 함께 리셋 링크 발송.