baron-sso/README.md

# Baron SSO

**Baron SSO**는 화이트 라벨링된 사용자 인증 허브이자 통합 런처입니다.
**Descope**를 활용하여 안전한 비밀번호 없는 인증(Enchanted Link)을 제공하며, Flutter로 구현된 커스텀 UI를 통해 매끄러운 사용자 경험을 보장합니다. Backend는 Go (Fiber)와 ClickHouse를 사용하여 대용량 감사 로그(Audit Log)를 관리합니다.

## 🏗 아키텍처 (Architecture)

### 0. Ory Stack
- Ory Kratos: 사용자 인증/계정 관리(Identity).
- Kratos Selfservice UI: Kratos 셀프서비스 플로우 UI.
- Ory Hydra: OAuth2/OIDC 발급 및 토큰 관리.
- Ory Keto: 권한/정책 기반 접근 제어.
- Oathkeeper: 인증/인가 프록시 및 라우팅 게이트웨이.

### 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
  - userfront가 바라보는 backend

### 2. userfront(Flutter Web/App)
- **Framework**: Flutter 3.32+
- **Key Packages**: `flutter_riverpod`, `go_router`
- **Features**:
  - 탭 기반 로그인 UI (비밀번호 기반 / 링크 기반 / QR 기반 등)

### 3. adminfront(Web)
- **Framework**: Vite, React 19+, Shadcn/ui 등
- **Features**:
  - 사용자 관리, 권한 부여 등 관리자 기능
  - 앱 별 사용량(호출량) 등 통계
  - 핵심 Audit 대상 

### 4. devfront(Web) - 향후 분리 예정
- **Framework**: Vite, React 19+, Shadcn/ui 등
- **Features**:
  - RP 등록 및 관리
  - RP별 Consent 관리


### 4. 주요 시나리오 (Core Scenarios)
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[adminfront] -->|"OIDC authorize/token (PKCE)"| HY["Hydra (OIDC 엔진)"]
  DF[devfront] -->|"OIDC authorize/token (PKCE)"| HY
  UF["userfront (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로 연결합니다.

---

## 🚀 시작하기 (Getting Started)

### 사전 요구사항 (Prerequisites)
- Docker & Docker Compose
- Flutter SDK (로컬 개발용)
- Go (로컬 백엔드 개발용)

### 환경 설정 (Environment Setup)
1. 예제 환경 설정 파일을 복사합니다.
   ```bash
   cp .env.sample .env
   ```
2. **중요**: `.env` 파일을 열어 **Descope Project ID**를 입력해야 합니다.
   ```env
   DESCOPE_PROJECT_ID=P2t...
   ```
3. **IDP 우선순위와 Ory 엔드포인트를 지정**합니다. 기본값은 Ory 우선 + Descope 폴백입니다.
   ```env
   IDP_PROVIDER=ory,descope
   KRATOS_ADMIN_URL=http://kratos:4434
   HYDRA_ADMIN_URL=http://hydra:4445
   HYDRA_PUBLIC_URL=http://hydra:4444
   ```

### 전체 스택 실행 (Running the Stack)

#### 1. 네트워크 생성 (최초 1회)
Ory Stack과 애플리케이션 간 통신을 위한 도커 네트워크를 생성합니다.
```bash
# ory-net은 bridge 모드로 생성
docker network create -d bridge ory-net
docker network create hydranet
docker network create kratosnet
```

#### 2. 인프라 및 Ory Stack 실행
데이터베이스와 Ory 서비스(Kratos, Hydra, Keto 등)를 실행합니다.
```bash
docker compose -f compose.infra.yaml -f compose.ory.yaml up -d
```

#### 3. 애플리케이션 실행
userfront와 backend 서비스를 실행합니다.
```bash
docker compose -f docker-compose.yaml up -d
```
(또는 한번에 실행: `docker compose -f compose.infra.yaml -f compose.ory.yaml -f docker-compose.yaml up -d`)

- **userfront**: http://localhost:5000 접속
- **backend**: http://localhost:3000 (API)
- **ClickHouse**: http://localhost:8123
- **Kratos Public**: http://localhost:4433
- **Hydra Public**: http://localhost:4444
- **Kratos UI**: http://localhost:4455

### MCP 서버 (Hydra/Kratos)
MCP 서버는 기존 Hydra/Kratos에 연결하며 별도 Ory 스택이나 포트를 추가로 띄우지 않습니다.  
프로덕션에서는 실행하지 않도록 `mcp` 프로파일을 로컬에서만 켜세요.

```bash
docker compose -f compose.ory.yaml --profile mcp up -d hydra-mcp-server kratos-mcp-server
```

- MCP 서버는 stdio 기반이라 외부 포트를 열지 않습니다.
- MCP 클라이언트에서 `npx`로 실행하는 설정 예시입니다.
- `hydra-mcp`는 첫 실행 시 캐시 디렉터리에 의존성을 자동 설치합니다(수동 `npm install` 불필요).

```toml
[mcp_servers.kratos-mcp]
command = "npx"
args = ["-y", "mcp-ory-kratos"]

[mcp_servers.kratos-mcp.env]
KRATOS_ADMIN_URL = "http://localhost:4434"

[mcp_servers.hydra-mcp]
command = "npx"
args = ["-y", "/home/lectom/repos/baron-sso/mcp/hydra-mcp"]

[mcp_servers.hydra-mcp.env]
HYDRA_PUBLIC_URL = "http://localhost:4441"
HYDRA_ADMIN_URL = "http://localhost:4445"
```

### 로컬 개발 (Manual)
Docker 없이 코드를 수정하며 개발하려면:

**Backend:**
```bash
cd backend
go mod tidy
go run cmd/server/main.go
```

**userfront:**
```bash
cd userfront
flutter pub get
flutter run -d chrome
```

**adminfront:**
```bash
cd adminfront
npm install
npm run dev
```

**devfront:**
```bash
cd devfront
npm install
npm run dev
```

---

## 📂 프로젝트 구조 (Project Structure)

```
baron_sso/
├── backend/            # Go Fiber 애플리케이션
│   ├── cmd/server/     # 진입점 (Entry point)
│   ├── internal/       # 도메인, 핸들러, 저장소(Repository)
│   └── Dockerfile
├── userfront/          # Flutter 애플리케이션
│   ├── src/            # UI 및 로직
│   └── pubspec.yaml
├── adminfront/         # 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         # 환경 설정 템플릿
└── README.md           # 본 파일
```

## 📝 상태 및 로드맵 (Status & Roadmap)
- [x] **Phase 1**: 초기 설정 및 아키텍처 설계 (완료)
- [x] **Phase 2**: Backend Audit API 구현 (일부 완료)
- [x] **Phase 3**: userfront 로그인 UI 인증 로직 (완료)
- [ ] **Phase 4**: adminfront 기능 추가 (예정)
- [ ] **Phase 5**: 대시보드 및 통합 런처 구현 (예정)