FractalOps 요구사항 SSOT

이 문서는 FractalOps가 관장하는 전체 스택의 요구사항 기준 문서다. 친절하게 말하면, “각 솔루션을 어떻게 인증하고, 누구에게 어떤 권한을 어떻게 투영(projection)하며, 어디서 검증하는가”를 한 곳에서 읽을 수 있게 모아둔 곳이다.

현재 스택/솔루션/IA의 최신 라우팅 기준은 Current Stack, Solution, and IA Map이 우선한다. 이 문서는 세부 요구사항 목차이며, 오래된 세부 문서와 충돌하면 current map을 기준으로 갱신한다.

목적

인증/인가/프로비저닝을 FractalOps 중심으로 표준화한다.
솔루션별 이질적인 RBAC/그룹 체계를 canonical ontology(/org/... group path + realm role)로 흡수한다.
재현 가능한 운영(SSOT env + topology + operation)을 강제한다.

이 문서들의 모든 인증/투영 항목은 코드의 단일 진실 원천(SSOT)인 backend/src/fractalops/application/identity/features/stack_identity_contract_catalog/resources/stack-identity-contract-catalog.json (topology_version: stack-identity-contract.v1)과 토폴로지 platform/k8s/environments/lxc-pve-lab/runtime.cue를 그대로 따른다. Helm values와 runtime contract는 생성된 검증 산출물이며 직접 수정하지 않는다. 추측으로 쓰지 않는다.

한눈에 보는 신뢰 경계

모든 직원용 솔루션은 단일 인증 경계인 Pomerium edge를 통과한다. 인증 권한 (authentication authority)은 스택마다 다르지만, 트래픽이 들어오는 문은 하나다 (auth.yamon.io, realm yamon, primary IdP alias microsoft).

flowchart LR
  User(["직원 / AI account"])
  Edge["Pomerium edge<br/>auth.yamon.io"]
  KC["Keycloak realm yamon<br/>keycloak.yamon.io"]
  Entra["Microsoft Entra<br/>(primary_idp_alias: microsoft)"]

  subgraph IdPClaims["OIDC claims 신뢰 스택"]
    Portal["Portal<br/>portal.yamon.io"]
    Penpot["Penpot"]
    DataHub["DataHub"]
    Daytona["Daytona"]
    Argo["Argo CD"]
    Windmill["Windmill"]
  end

  subgraph EdgeGate["pomerium_edge_gate 스택 (앱은 로컬 인증)"]
    Dokploy["Dokploy<br/>email_password"]
    Novu["Novu<br/>email_password"]
  end

  subgraph Forwarded["forwarded assertion 스택"]
    Nexus["Nexus<br/>forwarded_jwt_assertion"]
  end

  User --> Edge
  Edge -- OIDC --> KC
  KC -- broker --> Entra
  Edge --> IdPClaims
  Edge --> EdgeGate
  Edge --> Forwarded

OIDC claims 신뢰 스택: Keycloak(yamon realm)이 발급한 OIDC claim을 앱이 직접 신뢰한다. authentication_authority: external_idp, session_trust_adapter: pomerium.
pomerium_edge_gate 스택: 앱 자체는 SSO를 지원하지 않거나 enterprise 한정이라, edge에서 먼저 인증을 강제하고 앱 안에서는 로컬 세션(이메일/비밀번호 등)을 쓴다.
forwarded assertion 스택: edge가 검증한 JWT/토큰을 앱에 전달한다(예: Nexus 레지스트리).

문서 구조

flowchart TD
  index["요구사항 SSOT 목차"] --> common["공통 계약<br/>Canonical Contract"]
  index --> e2e["MCP E2E 시나리오"]
  common --> core["FractalOps Core"]
  common --> portal["Portal Control Plane"]
  common --> pomerium["Pomerium Edge"]
  common --> keycloak["Keycloak IdP"]
  common --> openbao["OpenBao Secret"]
  common --> temporal["Temporal Orchestration"]
  common --> penpot["Penpot"]
  common --> pve["Proxmox VE"]

요구사항 분류 체계 (Taxonomy)

각 스택 요구사항 문서는 다음 4개 축으로 정리된다. 이는 identity-contract catalog의 실제 필드를 그대로 따른다.

flowchart TD
  R["스택 요구사항"] --> A["1. 인증 권한<br/>authentication_authority"]
  R --> B["2. 세션 신뢰 어댑터<br/>session_trust_adapter"]
  R --> C["3. 디렉터리/권한 투영<br/>directory_projection_protocol +<br/>entitlement_projection_mechanism"]
  R --> D["4. 계정 실체화 전략<br/>account_materialization_strategy"]

  A --> A1["external_idp / stack_local /<br/>portal / keycloak"]
  B --> B1["pomerium / pomerium_edge_gate /<br/>portal / local_loopback"]
  C --> C1["scim / api / groups /<br/>oidc_claims / api_reference_only"]
  D --> D1["preprovisioned / jit /<br/>federated_session /<br/>local_invite_or_api_key /<br/>service_account"]

authentication_authority: 누가 로그인을 책임지는가. external_idp(Keycloak/Entra), stack_local(앱 로컬 계정), portal(포털 세션), keycloak(직접 Keycloak OIDC).
session_trust_adapter: edge에서 세션을 어떻게 신뢰하는가. 대부분 pomerium이며, 로컬 인증 스택은 pomerium_edge_gate로 edge를 먼저 통과시킨다.
directory/entitlement projection: 그룹/권한을 어떻게 전달하는가. SCIM, native API, OIDC groups claim, 또는 참조만(api_reference_only).
account_materialization_strategy: 계정을 미리 만드는가(preprovisioned), 접근 시점에 만드는가(jit), 세션만 연합하는가(federated_session).

스택별 신뢰 계약 요약표

stack-identity-contract-catalog.json의 실제 항목을 그대로 정리한 표다. 각 스택 문서는 이 표의 해당 행을 상세화한다.

스택	authentication_authority	authentication_protocol	session_trust_adapter	projection	account_materialization
penpot	external_idp	oidc	pomerium	api (`project_team_api`)	jit
keycloak	external_idp	oidc	pomerium	groups (`realm_admin_role`)	federated_session
datahub	external_idp	oidc	pomerium	scim (`scim_group_projection`)	jit
daytona	external_idp	oidc	pomerium	api (`workspace_claim_projection`)	jit
nexus	external_idp	oidc	pomerium	scim (`service_token_policy`)	brokered_session_or_service_token
windmill	external_idp	oidc	pomerium	scim (`scim_group_workspace_role`)	jit
argocd	external_idp	oidc	pomerium	groups (`oidc_group_rbac`)	federated_session
headlamp	external_idp	oidc	pomerium	groups (`oidc_cluster_rbac`)	federated_session
k3s	external_idp	oidc	pomerium	groups (`cluster_rbac`)	federated_session
langboard	external_idp	oidc	pomerium	scim (`project_role_scim`)	preprovisioned
dokploy	stack_local	email_password	pomerium_edge_gate	api_reference_only (`project_environment_role_api`)	local_invite_or_api_key
novu	stack_local	email_password	pomerium_edge_gate	api_reference_only (`notification_workflow_api_key`)	local_invite_or_api_key
redpanda	keycloak	oidc	pomerium_edge_gate	oidc_claims (`kafbat_ui_rbac_claims`)	oidc_jit
armory	portal	portal_session	portal	groups (`armory_profile_loadout`)	federated_session
playwrightgrid	portal	portal_session	portal	groups (`browser_lease_policy`)	brokered_session_or_service_token
searxnggrid	portal	portal_session	portal	groups (`mcp_runtime_policy`)	brokered_session_or_service_token
agent-memory-archive	portal	portal_session	portal	groups (`mcp_runtime_policy`)	brokered_session_or_service_token
fractalops-daytona-broker	external_idp	oidc_client_credentials	pomerium	api (`project_organization_reconciler`)	service_account
protected-registry-desktop	external_idp	oidc	local_loopback	scim (`project_package_claims`)	brokered_session

현재 Stack Operation Catalog

fops stacks list --compact 기준 현재 등록된 스택 목록이다.

argocd
clickhouse
cloudflared
daytona
datahub
dokploy
evidence
fractalops
gitops
headlamp
k3s
kafka
langboard
openbao-secret-delivery
penpot
pomerium
runtime-storage
nexus
windmill

완료 정의 (Definition of Done)

각 스택은 인증 흐름, 권한 모델, 동기화 방식(SCIM/JIT/Poll), 실패 처리, 운영 검증 항목을 갖는다.
하드코딩된 tenant/domain/token이 문서/코드 어디에도 남지 않는다(make infra-ssot-scan-strict).
모든 배포/설정은 operation 또는 topology/env 기반으로 재현 가능해야 한다.

구조 개선 계획 (L0-L3)

L0: SSOT 계약
- env/openbao/topology 외에 도메인·주소·토큰 상수 금지.
- 솔루션 권한 키는 solution_* canonical만 사용.
L1: 정책/토폴로지
- 권한 판정은 canonical group path(/org/...) + SpiceDB(ReBAC)/RBAC 계약으로만 수행.
- 솔루션 가시성은 정책 허용 + requiredRoles/requiredCollections 충족으로 단일화.
L2: 유저 시나리오 테스트
- 단위 테스트는 placeholder URL을 쓰지 않고 live 형태 URL로만 시나리오 검증.
- PM/Designer/Developer persona 시퀀스를 API 라우트 기준으로 검증.
L3: E2E 게이트
- MCP 시나리오 문서(e2e-scenarios-mcp.md)와 실제 결과를 동기화.
- FAIL 항목은 원인-완료조건-재검증 증거를 같은 문서에 누적.