kevin/baron-sso

Fork 0

forked from baron/baron-sso

Files

Lectom C Han 39594f8e21 README update

2026-01-28 17:30:23 +09:00

9.3 KiB

Raw Blame History

Baron SSO

Baron 통합로그인은 화이트 라벨링된 가족사의 모든 소프트웨어 Auth를 총괄하는 사용자 인증/인가 허브입니다.

Ory Stack으로 모든 구성요소를 self-hosting 합니다.
Backend는 Go (Fiber)로 구성된 Ory Stack의 유일한 Command 전송 포인트입니다. 모든 Command는 ClickHouse로 강제 전송되며 Audit Log 시스템을 구성합니다.
Front는 Backend를 통해서만 연동하며 자체가 Ory Stack의 RP기도 합니다. 크게 3개 계층으로 분리됩니다.
- UserFront: Flutter로 구현된 커스텀 UI를 통해 매끄러운 사용자 경험을 보장합니다.
  - 로그인 : 비밀번호, SMS, QR 스캔 등의 수단으로 로그인 가능
  - 향후 모바일 앱 지원으로 인증 Push 승인 등 MFA 확장 (예정)
  - 정보변경, 앱 연동 이력 확인 등 개인화 기능
  - 사용 가능한 앱 리스트 (예정)
- AdminFront: 사용자 관리 등 Admin 기능
- DevFront: RP 관리 등 개발자 기능

🏗 아키텍처 (Architecture)

0. Ory Stack

Ory Kratos: 사용자 인증/계정 관리(Identity).
Ory Hydra: OAuth2/OIDC 발급 및 토큰 관리.
Ory Keto: 권한/정책 기반 접근 제어.
Oathkeeper: 인증/인가 프록시 및 라우팅 게이트웨이.

flowchart
    subgraph Edge
      OK["Oathkeeper<br/>(Only Public Entry)"]
    end

    subgraph App
      BE["Backend<br/>(Only Upstream)"]
    end

    subgraph OryStack
      KR[Kratos]
      HY[Hydra]
      KE[Keto]
      KR --- HY --- KE
    end
    BE -->|Command| OryStack
    OK -->|Query| KR
    OK -->|Query| HY
    OK -->|Query| KE

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)

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

전체 연결 구조도

flowchart TD
    subgraph Clients ["External Clients"]
        AF[adminfront]
        DF[devfront]
        UF["userfront"]
        DS["일반SW"]
    end

    subgraph AppService ["Control Plane"]
        BE["Backend (Command/Audit Controller)"]
    end

    subgraph OryBundle ["Ory Deployment Stack"]
        direction TB
        OK["Oathkeeper (Public Proxy/OIDC)"]
        
        subgraph OryEngines ["Ory Services"]
            direction LR
            HY["Hydra"]
            KR["Kratos"]
            KE["Keto"]
        end
        
        ICH[(Internal Clickhouse)]
        
        %% Internal Flow within Bundle
        OK -->|Routing/Queries| OryEngines
        OK -.->|Access/Usage Log| ICH
    end

    subgraph AuditDB ["Audit Storage"]
        ECH[(External Clickhouse)]
    end

    %% Key Command Path
    AF & DF & UF & DS ==>|Actions / Commands| BE
    
    %% Backend Responsibilities
    BE -->|Admin/State Control| OryEngines
    BE -.->|Mandatory Audit Log| ECH

    %% Connection Note (Hidden flow mentioned in logic)
    %% OK is technically the entry for OIDC, but removed as per request

    %% Styles
    style OryBundle fill:#f8f9fa,stroke:#333,stroke-width:2px
    style BE fill:#bbf,stroke:#333,stroke-width:2px
    style ECH fill:#fdd,stroke:#333
    style ICH fill:#dfd,stroke:#333
    style OK fill:#f9f,stroke:#333
    style OryEngines fill:#fff,stroke:#999,stroke-dasharray: 5 5

Kratos가 사용자 SoT이며 Hydra는 순수 OIDC 토큰 엔진입니다. 비지니스로직은 Backend를 통해서, 기본 인증 로직은 Ory Stack을 통해 진행됩니다.

🚀 시작하기 (Getting Started)

사전 요구사항 (Prerequisites)

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

환경 설정 (Environment Setup)

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

IDP 우선순위와 Ory 엔드포인트를 지정합니다. 기본값은 Ory 우선 + Descope 폴백입니다.

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과 애플리케이션 간 통신을 위한 도커 네트워크를 생성합니다.

# 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 등)를 실행합니다.

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

3. 애플리케이션 실행

userfront와 backend 서비스를 실행합니다.

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/Keto)

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

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

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

[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"

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

[mcp_servers.keto-mcp.env]
KETO_READ_URL = "http://localhost:4466"
KETO_WRITE_URL = "http://localhost:4467"

로컬 개발 (Manual)

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

Backend:

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

userfront:

cd userfront
flutter pub get
flutter run -d chrome

adminfront:

cd adminfront
npm install
npm run dev

devfront:

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)

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

9.3 KiB Raw Blame History