baron-sso/docs/SoT_Architecture_Policy.md

Baron SSO Data SoT (Source of Truth) Architecture Policy

1. Core Principle: "Ory Stack is the Single Source of Truth"

Baron SSO 시스템에서 인증(Identity), 인가(Authorization), OAuth2 위임(Delegation)의 데이터 원천은 Ory Stack (Kratos, Keto, Hydra) 입니다. Backend의 로컬 데이터베이스(PostgreSQL)는 성능 최적화, 검색, 감사(Audit), 비즈니스 메타데이터 관리를 위한 Read-Model 및 Cold Storage의 역할만 수행합니다.

2. Component Policies

2.1 Identity & User Profile (Ory Kratos)

• SoT: Ory Kratos Identity (traits, metadata_public)
• Local DB (users Table): Read-Model & Search Index
  • 목적: 대규모 사용자 목록의 고속 검색(LIKE), 필터링, 정렬, 테넌트 조인(Join) 지원.
  • 동기화 전략: Async Write-Behind
    • 사용자 생성/수정 API는 Kratos 처리가 성공하면 즉시 성공 응답을 반환합니다.
    • 로컬 DB 동기화는 별도 고루틴(Goroutine)에서 비동기로 수행됩니다.
  • 장애 격리: 로컬 DB 장애가 사용자의 로그인/가입 프로세스를 차단하지 않습니다.

2.2 Permissions & Relationships (Ory Keto)

• SoT: Ory Keto (Relation Tuples)
• Local DB:
  • 권한 판단 로직을 로컬 DB에 저장하지 않습니다.
  • Tenant, TenantGroup 등 비즈니스 객체의 생성/삭제 이벤트를 Keto의 관계(Relation)로 비동기 동기화합니다.
  • 모든 권한 검증(CheckPermission)은 반드시 Keto API를 통해 실시간으로 수행합니다.

2.3 OAuth2 Clients & Sessions (Ory Hydra)

• SoT: Ory Hydra (OAuth2 Clients, Access/Refresh Tokens, Consent Sessions)
• Local DB (client_secrets, client_consents): Backup & Query-Model
  • client_secrets: Hydra는 해시된 시크릿만 저장하므로, 시크릿 재발급 및 관리를 위한 **원본 보관소(Cold Storage)**로 사용합니다.
  • client_consents: Hydra API는 "특정 사용자의 동의 내역" 조회만 지원하므로, "특정 클라이언트의 전체 사용자 동의 목록"을 제공하기 위한 **조회용 모델(Query-Model)**로 사용합니다.

3. Data Flow & Synchronization Strategy

3.1 Write Path (Command)

1. Request: 클라이언트가 Backend API 요청.
2. Ory Exec: Backend가 Ory 서비스(Kratos/Hydra/Keto) API를 동기(Synchronous) 호출.
3. Response: Ory 성공 시 클라이언트에게 즉시 성공 응답 반환 (SoT 확정).
4. Sync: Backend가 비동기(Goroutine)로 로컬 DB 테이블을 갱신.

3.2 Read Path (Query)

• Self Context (내 정보, 내 권한): Ory Session/Token을 통해 직접 검증하거나 Kratos/Keto를 실시간 조회 (Always Fresh).
• Admin Context (목록 조회, 검색): 로컬 DB를 조회하여 빠른 응답 제공 (Eventually Consistent).

3.3 Conflict Resolution

• 데이터 불일치가 발견될 경우, 항상 **Ory Stack의 데이터를 기준(Authority)**으로 로컬 DB를 보정(Self-healing)합니다.