Files

송대일 c1a1fcb041 Fix local Docker startup configuration

2026-06-10 20:18:58 +09:00

9.1 KiB

Raw Blame History

Baron SSO 구조 분석

1. 이 시스템은 무엇인가

Baron SSO는 계열사 또는 화이트라벨 대상 서비스들의 로그인, 권한, 애플리케이션 연동을 중앙에서 관리하는 통합 인증/인가 허브입니다. 저장소의 설명과 구성 파일을 보면 단순 로그인 화면이 아니라 다음 역할을 함께 수행하는 IAM 플랫폼에 가깝습니다.

사용자 인증과 계정 수명주기 관리
OAuth2/OIDC 기반 SSO와 RP(Relying Party) 연동
권한 정책 및 접근 제어 관리
관리자용 운영 화면, 개발자용 RP 관리 화면, 조직도/조직 컨텍스트 화면 제공
감사 로그 수집과 운영 데이터 관리

핵심적으로는 Ory Stack을 자체 호스팅하고, Baron Backend가 비즈니스 규칙과 운영 기능을 담당하며, 여러 프론트엔드가 역할별 UI를 제공합니다.

2. 전체 아키텍처 요약

현재 저장소는 하나의 애플리케이션이 아니라, 인증 인프라와 여러 사용자 인터페이스를 함께 운영하는 멀티 서비스 구조입니다.

2.1 주요 계층

Ory 기반 IAM 계층
Baron 자체 백엔드 계층
역할별 프론트엔드 계층
게이트웨이 및 인프라 계층
데이터 저장소 및 로깅 계층

2.2 구성 요소별 역할

Ory Stack

compose.ory.yaml 기준으로 다음 컴포넌트를 별도 컨테이너로 운영합니다.

Kratos: 사용자 인증, 계정, self-service flow
Hydra: OAuth2/OIDC 서버, 로그인/동의 흐름, 토큰 발급
Keto: 권한 관계 및 정책 기반 접근 제어
Oathkeeper: 프록시형 접근 제어 게이트

즉, Baron SSO의 인증/인가 핵심은 Ory를 기반으로 하고, Baron 코드는 그 위에서 비즈니스 로직과 운영 기능을 덧씌우는 구조입니다.

Backend

backend는 Go Fiber 기반 API 서버이며, 저장소 README 설명대로 Ory Stack과 여러 프론트엔드 사이의 주된 비즈니스 백엔드 역할을 수행합니다.

역할은 다음과 같이 해석할 수 있습니다.

프론트엔드가 호출하는 자체 API 제공
Ory Admin/Public API와 연동하여 로그인, 동의, RP 관련 흐름 제어
감사 로그 적재
테넌트, 사용자, 운영 데이터 처리
외부 연동 기능 처리

docker-compose.yaml에서도 각 웹 프론트엔드가 API_PROXY_TARGET=http://baron_backend:3000으로 이 백엔드를 바라보도록 구성되어 있습니다.

프론트엔드 계층

역할이 나뉜 여러 UI가 함께 존재합니다.

userfront: 최종 사용자용 로그인/인증 UI, Flutter 기반
adminfront: 관리자용 운영 UI, React/Vite 기반
devfront: 개발자용 RP 및 연동 관리 UI, React/Vite 기반
orgfront: 조직/컨텍스트 시각화 및 관리 성격의 UI, React/Vite 기반

프론트엔드가 분리되어 있다는 점은 이 시스템이 단일 로그인 페이지 수준이 아니라, 사용자 포털과 운영 포털을 함께 포함하는 플랫폼임을 보여줍니다.

Gateway

gateway는 Nginx 기반 컨테이너이며 외부 진입점 역할을 담당합니다. compose.infra.yaml에서 public_net에 연결되어 있고, USERFRONT_PORT를 외부로 노출합니다. 따라서 사용자가 처음 접근하는 표면은 게이트웨이 또는 Oathkeeper를 포함한 프록시 계층을 통해 노출되는 구조로 볼 수 있습니다.

데이터 및 부가 인프라

저장소에는 인증 인프라용 저장소와 서비스 메타데이터용 저장소가 분리되어 있습니다.

PostgreSQL: Baron 메타데이터 저장 및 Ory 데이터 저장소
ClickHouse: 감사 로그 및 이벤트성 데이터 적재
Redis: 캐시/세션성 또는 보조 저장소 용도
Promtail, Blackbox Exporter, Vector: 로그/모니터링/전송 보조 구성

2.3 구조도

flowchart LR
    User[User / Admin / Developer] --> Gateway[Nginx Gateway / Public Entry]
    User --> WebApps[Frontends]

    subgraph Frontend Layer
      UF[userfront\nFlutter]
      AF[adminfront\nReact + Vite]
      DF[devfront\nReact + Vite]
      OF[orgfront\nReact + Vite]
    end

    Gateway --> UF
    AF --> BE
    DF --> BE
    OF --> BE
    UF --> BE

    subgraph Service Layer
      BE[Baron Backend\nGo + Fiber]
    end

    subgraph IAM Layer
      KR[Ory Kratos]
      HY[Ory Hydra]
      KE[Ory Keto]
      OK[Ory Oathkeeper]
    end

    BE --> KR
    BE --> HY
    BE --> KE
    OK --> KR
    OK --> HY
    OK --> KE

    subgraph Data Layer
      PG[(PostgreSQL)]
      CH[(ClickHouse)]
      RD[(Redis)]
    end

    BE --> PG
    BE --> CH
    BE --> RD
    KR --> PG
    HY --> PG
    KE --> PG

3. 개발 기술 스택 정리

3.1 백엔드

Language: Go 1.26.2
Web Framework: Fiber v2
ORM/DB access: GORM, PostgreSQL driver, lib/pq
IAM/OIDC 관련: coreos/go-oidc, golang.org/x/oauth2, go-jose
Cache/infra: Redis, ClickHouse
Test: Testify, Testcontainers
기타 연동: AWS SDK v2, SES

즉, 백엔드는 Go 기반의 API 서버이면서 IAM 흐름을 직접 제어하는 오케스트레이션 계층입니다.

3.2 사용자 프론트엔드

userfront/pubspec.yaml 기준 스택은 다음과 같습니다.

Framework: Flutter
Language runtime: Dart SDK 3.10+
State management: Riverpod
Routing: go_router
기타: easy_localization, qr_flutter, mobile_scanner, shared_preferences

이를 보면 userfront는 웹 중심 React 앱이 아니라 Flutter 기반의 사용자 인증 UI이며, QR 로그인, 다국어, 로컬 상태 저장 등의 기능을 염두에 둔 구조입니다.

3.3 운영/관리 프론트엔드

adminfront, devfront, orgfront는 공통적으로 현대적인 React 프론트엔드 스택을 사용합니다.

Framework: React 19
Build tool: Vite 8
Language: TypeScript 6
Styling: Tailwind CSS, tailwindcss-animate
UI primitives: Radix UI
Data fetching/cache: TanStack Query
Form/validation: react-hook-form, zod
Auth client: oidc-client-ts, react-oidc-context
HTTP client: axios
Test: Vitest, Playwright
Lint/format: Biome

orgfront는 여기에 @xyflow/react를 사용하고 있어 조직 구조나 컨텍스트 시각화 성격의 기능이 포함된 것으로 보입니다.

3.4 공통/모노레포 구성

Package manager: pnpm workspace
공통 패키지: common
공통 리소스: locales
코드 품질: Biome

즉, 프론트엔드는 모노레포 형태로 운영되며 공통 UI/설정/로케일 자산을 공유합니다.

3.5 인프라 및 배포

Container orchestration: Docker Compose
Reverse proxy: Nginx
IAM platform: Ory Kratos, Hydra, Keto, Oathkeeper
Database: PostgreSQL
Analytics/Audit store: ClickHouse
Cache: Redis
Observability: Promtail, Vector, Blackbox Exporter

4. 이 저장소에서 보이는 설계 특징

4.1 멀티테넌트 운영 시스템 성격

README와 seed-tenant.csv, 테넌트 import/export 관련 문서 이름들로 보아 이 시스템은 단일 서비스용 로그인 서버가 아니라, 여러 조직과 테넌트를 관리하는 멀티테넌트 IAM 운영 시스템입니다.

4.2 인증과 운영 기능의 분리

인증 그 자체는 Ory Stack이 맡고, Baron Backend와 각 Frontend가 다음을 담당합니다.

비즈니스 규칙 적용
운영 UI 제공
테넌트/사용자 관리
RP 등록 및 OIDC 연동 관리
감사 로그와 운영성 기능

이 구조는 범용 IAM 엔진과 도메인 특화 운영 시스템을 분리한 설계로 볼 수 있습니다.

4.3 감사와 추적 가능성을 중시

ClickHouse, Promtail, Vector, 감사 로그 관련 README 설명을 보면 운영 추적성과 감사 가능성을 중요한 요구사항으로 두고 있습니다. 특히 로그인/권한/관리자 작업의 추적을 고려한 구조로 해석됩니다.

4.4 역할별 UI 분리

최종 사용자, 운영 관리자, 개발자, 조직 관리 성격의 UI가 분리되어 있어 권한과 업무 맥락에 따라 화면을 구분하는 B2B 운영 시스템의 전형적인 구조를 가집니다.

5. 한 줄 요약

Baron SSO는 Ory Stack을 자체 호스팅 기반으로 사용하면서, Go 백엔드와 여러 역할별 프론트엔드를 결합해 구성한 멀티테넌트 SSO/IAM 운영 플랫폼입니다. 기술적으로는 Go + Fiber, Flutter, React + Vite + TypeScript, PostgreSQL, ClickHouse, Redis, Docker Compose, Ory 생태계를 중심으로 구성되어 있습니다.

6. 분석 시 참고한 주요 근거 파일

README.md
docker-compose.yaml
compose.infra.yaml
compose.ory.yaml
backend/go.mod
adminfront/package.json
devfront/package.json
orgfront/package.json
userfront/pubspec.yaml
pnpm-workspace.yaml

7. 주의사항

루트 README의 일부 프로젝트 구조 설명은 현재 저장소의 실제 구성과 완전히 일치하지 않을 수 있습니다. 예를 들어 adminfront, devfront, orgfront는 실제로 React/Vite 기반 패키지이고, userfront는 별도의 Flutter 애플리케이션입니다. 따라서 현재 구조 분석은 README 서술보다 실제 매니페스트와 compose 파일을 우선 기준으로 정리했습니다.

9.1 KiB Raw Blame History