kevin/baron-sso
1
0
Fork 0
forked from baron/baron-sso
Code Pull Requests Activity
Files
5c19b88230a0c4baf02bd20b3cf8d45d72dab35e
baron-sso/README.md
Lectom C Han 5c19b88230 문서 업데이트
2026-01-27 17:59:17 +09:00

5.5 KiB
Raw Blame History

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
    • 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 통합로그인 서비스에 로그인된 상태에서 런처를 통해 타 앱/서비스로 이동 (자동 로그인). 1.1. 단 약관동의(Consent) 이력이 없으면 Consent 단계로 이동
  2. Cross-Device Auth: 이메일 SMS 등의 수단으로 링크를 전달받고 해당 링크를 사용자가 클릭하면 최초 로그인 요청한 세션이 활성화 2.1 향후 App Push 등 2차 인증 강화수단 검토 필요
  3. QR Login: 최초 진입 시 사전 로그인되어 있는 웹/앱을 이용해 QR 코드를 스캔하여, QR코드가 로딩된 Device를 로그인 상태로 전환

전체 연결 구조도

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로 연결합니다.

🚀 시작하기 (Getting Started)

사전 요구사항 (Prerequisites)

  • Docker & Docker Compose
  • Flutter SDK (로컬 개발용)
  • Go (로컬 백엔드 개발용)

환경 설정 (Environment Setup)

  1. 예제 환경 설정 파일을 복사합니다. 
    cp .env.sample .env
  2. 중요: .env 파일을 열어 Descope Project ID를 입력해야 합니다. 
    DESCOPE_PROJECT_ID=P2t...

전체 스택 실행 (Running the Stack)

1. 인프라 실행 (데이터베이스)

데이터 레이어를 먼저 실행합니다.

docker compose -f compose.infra.yaml up -d

2. 애플리케이션 실행

Frontend와 Backend 서비스를 실행합니다.

docker compose up

로컬 개발 (Manual)

Docker 없이 코드를 수정하며 개발하려면:

Backend:

cd backend
go mod tidy
go run cmd/server/main.go

Frontend:

cd frontend
flutter pub get
flutter run -d chrome

📂 프로젝트 구조 (Project Structure)

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

📝 상태 및 로드맵 (Status & Roadmap)

  • Phase 1: 초기 설정 및 아키텍처 설계 (완료)
  • Phase 2: Backend Audit API 구현 (일부 완료)
  • Phase 3: User Front 로그인 UI 인증 로직 (완료)
  • Phase 4: Admin Front 기능 추가 (예정)
  • Phase 5: 대시보드 및 통합 런처 구현 (예정)
View Git Blame Copy Permalink