kevin/baron-sso
1
0
Fork 0
forked from baron/baron-sso
Code Pull Requests Activity

문서 업데이트

Browse Source
This commit is contained in:
Lectom C Han
2026-01-27 17:56:17 +09:00
parent 5fa0af8d2e
commit 5c19b88230
8 changed files with 152 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
README.md
View File

@@ -5,27 +5,68 @@
## 🏗 아키텍처 (Architecture)
### 1. Frontend (Flutter Web)
- **Framework**: Flutter 3.32+
- **Organization**: `kr.co.baroncs`
- **Key Packages**: `descope`, `flutter_riverpod`, `go_router`
- **Features**:
- 탭 기반 로그인 UI (이메일 / SMS)
- Descope SDK 연동 (Enchanted Link)
### 0. Ory Stack
- Ory Kratos: 사용자 인증/계정 관리(Identity).
- Kratos Selfservice UI: Kratos 셀프서비스 플로우 UI.
- Ory Hydra: OAuth2/OIDC 발급 및 토큰 관리.
- Ory Keto: 권한/정책 기반 접근 제어.
- Oathkeeper: 인증/인가 프록시 및 라우팅 게이트웨이.
### 2. Backend (Go Fiber)
### 1. Backend (Go Fiber)
- **Language**: Go 1.25+
- **Framework**: Fiber v2.25+
- **Database**:
- **ClickHouse**: 감사 로그 (고성능 데이터 수집)
- **PostgreSQL**: 메타데이터 저장소 (Primary)
- **Features**:
- 인증용 SMS 발송 등 Ory-Stack으로 구현 어려운 부분 직접 구현
- `POST /api/v1/audit`: 감사 로그 수집 API
- User-Front가 바라보는 backend
### 2. User-Front(Flutter Web/App)
- **Framework**: Flutter 3.32+
- **Key Packages**: `flutter_riverpod`, `go_router`
- **Features**:
- 탭 기반 로그인 UI (비밀번호 기반 / 링크 기반 / QR 기반 등)
### 3. Admin-Front(Web)
- **Framework**: Vite, React 19+, Shadcn/ui 등
- **Features**:
- 사용자 관리, 권한 부여 등 관리자 기능
- 앱 별 사용량(호출량) 등 통계
- 핵심 Audit 대상
### 4. Dev-Front(Web) - 향후 분리 예정
- **Framework**: Vite, React 19+, Shadcn/ui 등
- **Features**:
- RP 등록 및 관리
- RP별 Consent 관리
### 4. 주요 시나리오 (Core Scenarios)
1. **Same Browser SSO**: Baron SSO에 로그인된 상태에서 런처를 통해 타 앱/서비스로 이동 (자동 로그인).
2. **Cross-Device Auth**: PC에서 로그인 시도 시, 이미 로그인된 모바일 앱으로 알림을 보내 승인 (Enchanted Link 활용).
3. **Clean Login**: 최초 진입 시 이메일 또는 SMS를 통한 로그인 (향후 OTP, MFA 확장 예정).
1. **Same Browser SSO**: Baron 통합로그인 서비스에 로그인된 상태에서 런처를 통해 타 앱/서비스로 이동 (자동 로그인).
1.1. 단 약관동의(Consent) 이력이 없으면 Consent 단계로 이동
2. **Cross-Device Auth**: 이메일 SMS 등의 수단으로 링크를 전달받고 해당 링크를 사용자가 클릭하면 최초 로그인 요청한 세션이 활성화
2.1 향후 App Push 등 2차 인증 강화수단 검토 필요
3. **QR Login**: 최초 진입 시 사전 로그인되어 있는 웹/앱을 이용해 QR 코드를 스캔하여, QR코드가 로딩된 Device를 로그인 상태로 전환
### 전체 연결 구조도
```mermaid
flowchart LR
AF[Admin Front] -->|"OIDC authorize/token (PKCE)"| HY["Hydra (OIDC 엔진)"]
DF[Dev Front] -->|"OIDC authorize/token (PKCE)"| HY
UF["User Front (Login/Consent UI)"] <-->|Hydra login/consent redirect| HY
UF -->|Kratos Browser Flow| KR["Kratos (SoT: identities/traits)"]
KR -->|subject=identity.id| HY
HY -->|ID/Access Token| RP[Relying Party Apps]
MG["Magic Link Wrapper (Fiber)"] -->|1회용 토큰→Kratos CreateSession| KR
MG -->|"Hydra Login Accept (옵션)"| HY
DS["Descope/Social IDP"] -->|Kratos Social/OIDC| KR
```
Kratos가 사용자 SoT이며 Hydra는 순수 OIDC 토큰 엔진입니다. Magic Link는 Fiber 래퍼가 Kratos 세션을 만들고 필요 시 Hydra Login Accept를 수행합니다. Descope 등 보조 IDP는 Kratos Social/OIDC provider로 연결합니다.
---
@@ -91,9 +132,13 @@ baron_sso/
│ ├── cmd/server/ # 진입점 (Entry point)
│ ├── internal/ # 도메인, 핸들러, 저장소(Repository)
│ └── Dockerfile
├── frontend/ # Flutter 애플리케이션
│ ├── lib/ # UI 및 로직
├── user-front/ # Flutter 애플리케이션
│ ├── src/ # UI 및 로직
│ └── pubspec.yaml
├── admin-front/ # React 기반 관리
│ ├── src/ # UI 및 로직
│ └── pubspec.yaml
├── compose.ory-stack.yaml # DB 서비스 (Postgres, ClickHouse)
├── compose.infra.yaml # DB 서비스 (Postgres, ClickHouse)
├── docker-compose.yaml # 앱 서비스 (Front, Back)
├── .env.sample # 환경 설정 템플릿
@@ -102,7 +147,7 @@ baron_sso/
## 📝 상태 및 로드맵 (Status & Roadmap)
- [x] **Phase 1**: 초기 설정 및 아키텍처 설계 (완료)
- [x] **Phase 2**: Backend Audit API 구현 (완료)
- [x] **Phase 3**: Frontend 로그인 UI 및 Descope 인증 로직 (완료)
- [ ] **Phase 4**: Frontend - Backend 연동 (Audit 전송) (예정)
- [x] **Phase 2**: Backend Audit API 구현 (일부 완료)
- [x] **Phase 3**: User Front 로그인 UI 인증 로직 (완료)
- [ ] **Phase 4**: Admin Front 기능 추가 (예정)
- [ ] **Phase 5**: 대시보드 및 통합 런처 구현 (예정)

0
AGENTS.md → docs/AGENTS.md
View File

0
Gemini.md → docs/Gemini.md
View File

27
docs/idp_policy.md Normal file
View File

@@ -0,0 +1,27 @@
# 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` 구현체만 교체하면, 데이터 마이그레이션을 제외한 모든 서비스가 중단 없이 동작해야 합니다.

0
PRD.md → docs/initial_PRD.md
View File

64
docs/shadowing_policy.md Normal file
View File

@@ -0,0 +1,64 @@
# 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 우선**: 사용자는 비밀번호 입력 없이 계속 이용 가능.
- **재설정 유도**: 비밀번호 사용 필수 시, "보안 정책 변경" 안내와 함께 리셋 링크 발송.

61
docs/tenant_policy.md
View File

@@ -1,61 +0,0 @@
# Tenant 정책 (Tenant Policy)
## 1. 개요 (Overview)
Baron SSO는 **Multi-Tenancy**를 지원하여, 단일 인스턴스에서 여러 조직(Tenant)의 데이터와 사용자를 격리하여 관리할 수 있다. 이 문서는 테넌트의 계층 구조, 리소스 소유권, 데이터 모델링 및 보안 정책을 정의한다.
---
## 2. 계층 구조 및 제약 (Hierarchy & Constraints)
### 2.1 계층 제한 (Depth Limit)
복잡성을 통제하기 위해 테넌트 계층은 **최대 2 Depth (1단계 깊이)**까지만 허용한다.
* **Root Tenant (Level 1)**: 최상위 조직 (예: 본사, 고객사 A)
* **Sub Tenant (Level 2)**: 하위 조직 (예: 인사팀, 지사 B)
* **제약**: Sub Tenant 밑에 또 다른 Tenant를 둘 수 없다.
### 2.2 리소스 소유권 (Resource Ownership)
* **Root Tenant Only**:
* **Relying Party (Client App)**, **IDP 설정** 등 시스템의 핵심 리소스는 **오직 Root Tenant만 생성하고 소유**할 수 있다.
* 모든 정책(Policy) 결정 권한은 Root Tenant에게 있다.
* **Sub Tenant**:
* 독자적인 RP나 IDP 설정을 가질 수 **없다**.
* Root Tenant가 설정한 리소스를 공유하며, 단순히 사용자를 그룹핑하거나 조직 단위(Organizational Unit)로 관리하는 역할만 수행한다.
---
## 3. 데이터 모델 (Data Model)
### 3.1 사용자 관계 (User Membership)
사용자는 **단일 계정(User ID)으로 여러 Tenant에 동시에 소속(N:M 관계)**될 수 있다.
* **`users` 테이블**: 사용자의 고유 식별자 및 전역 속성(Email, Name, Phone)만 저장.
* **`tenants` 테이블**: 테넌트 메타데이터 (`id`, `parent_id`, `name` 등). `parent_id`가 NULL이면 Root Tenant이다.
* **`user_tenants` 테이블 (Membership)**: `user_id`와 `tenant_id`를 매핑하며, 해당 테넌트 내에서의 `roles`(권한) 정보를 저장한다.
### 3.2 ID 식별 및 매핑 (Identification)
* **Internal Tenant ID**: 시스템 내부적으로는 항상 **UUID** 기반의 고유 식별자를 사용한다.
* **External Mapping**: Descope, Ory Hydra 등 외부 IDP의 Tenant ID 형식이 다를 수 있으므로, `provider_mappings` 컬럼(또는 테이블)을 통해 외부 ID와 내부 UUID를 매핑한다.
---
## 4. 인증 및 인가 (Authentication & Authorization)
### 4.1 Active Tenant Context
사용자가 여러 Tenant에 속할 수 있으므로, 모든 API 요청은 **"현재 어떤 Tenant 문맥에서 작업 중인가"**를 명확히 해야 한다.
* **Header**: `X-Tenant-ID` (필수)
* **Middleware 검증 로직**:
1. 요청 헤더에서 `TargetTenantID`를 추출한다.
2. User의 JWT Claims(또는 DB)를 확인하여, 사용자가 `TargetTenantID`에 소속되어 있는지 확인한다.
3. 해당 Tenant에서의 Role(예: Tenant Admin)이 요청한 작업을 수행할 권한이 있는지 검증한다.
---
## 5. 보안 및 감사 (Security & Audit)
### 5.1 Audit Log 정책
`X-Tenant-ID` 헤더의 존재 여부와 관계없이, **모든 보안 이벤트는 반드시 기록**되어야 한다.
* **Tenant Context 존재 시**: 해당 `tenant_id`와 함께 로그 저장.
* **Tenant Context 부재 시** (예: 로그인 직후, 프로필 수정, 내 테넌트 목록 조회): `tenant_id`를 `NULL` 또는 예약어(`system`, `personal`)로 저장.
### 5.2 API 접근 제어 정책
* **Tenant-Scoped API** (예: RP 생성, 멤버 초대): 헤더 누락 시 **400 Bad Request** 거절.
* **User/Global API** (예: 내 정보 수정): 헤더 누락 허용 (Global Context).

27
to-do.md
View File

@@ -1,27 +0,0 @@
# Baron SSO 작업 목록 (To-Do)
## 1. 백엔드 개발 (Go Fiber)
- [x] Go 모듈 초기화
- [x] Fiber 아키텍처 (Clean Arch) 구성
- [x] Audit Log DB 구축 (PostgreSQL + ClickHouse)
- [x] 프론트엔드 연동용 API 생성 (`POST /api/v1/audit`)
## 2. Descope 연동 전략
- [x] Ncloud SMS 커넥터 설정 (Descope Console)
- [x] Audit Log Webhook/API 설계
## 3. 프론트엔드 개발 (Flutter Web PoC)
- [x] Flutter 프로젝트 초기화
- [x] 로그인 UI 구현 (탭: 이메일/비번 & SMS)
- [x] Enchanted Link 핸들링 로직 구현 (Cross-Device Auth 지원)
- [ ] 대시보드 구현 (세션 리스트)
- [ ] 통합 런처 UI 구현 (Same Browser SSO)
- [ ] 관리자 모드 (Descope 관리 기능)
## 4. 검증 (Verification)
- [ ] End-to-End 로그인 흐름 테스트
- [ ] Audit Log 저장 확인
## 5. 향후 마일스톤 (Milestones)
- [ ] Passkey 지원 (Scenario 2, 3)
- [ ] 심화 MFA (OTP 등) 확장