kevin/baron-sso
1
0
Fork 0
forked from baron/baron-sso
Code Pull Requests Activity
Files
742964cf71eb024fbecb66aa9986e05ae1802937
baron-sso/README.md
Lectom C Han ff17259117 oathkeeper 동작 확인
2026-01-28 20:07:52 +09:00

9.5 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)

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

  1. 예제 환경 설정 파일을 복사합니다. 
    cp .env.sample .env
  2. 중요: .env 파일을 열어 Descope Project ID를 입력해야 합니다. 
    DESCOPE_PROJECT_ID=P2t...
  3. 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)

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 기반이라 외부 포트를 열지 않습니다.
  • 최초 실행시거나 빌드된 이미지가 없으면 `docker compose -f mcp/compose.mcp.ory.yaml build' 후에 사용 가능합니다
[mcp_servers.kratos-mcp]
command = "docker"
args = ["compose", "-f", "mcp/compose.mcp.ory.yaml", "run", "--rm", "--no-deps", "kratos-mcp-server"]

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

[mcp_servers.hydra-mcp]
command = "docker"
args = ["compose", "-f", "mcp/compose.mcp.ory.yaml", "run", "--rm", "--no-deps", "hydra-mcp-server"]

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

[mcp_servers.keto-mcp]
command = "docker"
args = ["compose", "-f", "mcp/compose.mcp.ory.yaml", "run", "--rm", "--no-deps", "keto-mcp-server"]

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

로컬 개발 (Manual)

Docker 없이는 개발할 수 없지만 Backend 및 [user/admin/dev]Front 코드는 개발모드로 수정하며 개발가능. 백그라운드로 infra 및 ory stack이 구동중이라는 가정

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: 대시보드 및 통합 런처 구현 (예정)
View Git Blame Copy Permalink