Penpot 요구사항

Penpot 요구사항

identity-contract: stack_type: design_collaboration · authentication_authority: external_idp · authentication_protocol: oidc · session_trust_adapter: pomerium · identity_assertion_mode: oidc_claims · directory_projection_protocol: api · entitlement_projection_mechanism: project_team_api · account_materialization_strategy: jit · projection_scope: project

목표

• 직원 접근 시 계정/권한을 JIT(Just-In-Time)로 보정한다.
• 이중 로그인을 제거한다(가능 범위 내).

Penpot은 디자이너 협업 도구다. 계정은 접근 시점에 생성(jit)되고, 권한은 Penpot의 native project/team API(project_team_api)로 투영된다. SCIM이 아니라 native API 투영이라는 점이 핵심이다.

인증/투영 흐름

sequenceDiagram
  autonumber
  participant U as 디자이너
  participant P as Portal launch
  participant E as Pomerium edge
  participant KC as Keycloak (client: penpot)
  participant PP as Penpot<br/>(penpot.yamon.io)
  participant API as FractalOps API

  U->>P: Penpot launch 클릭
  P->>API: IDP profile 보정 (email/firstName/lastName)
  Note over API: FRACTALOPS_PORTAL_IDP_PROFILE_ENFORCE_SOLUTIONS 대상
  U->>E: penpot.yamon.io 접근
  E->>KC: OIDC authorize (client penpot)
  KC-->>E: id_token (email, groups, preferred_username)
  E->>PP: /api/auth/oidc/callback
  PP->>PP: JIT 계정 생성/매핑
  API->>PP: project/team API 권한 투영 (poll)

OIDC client (catalog 실값)

stack-identity-contract-catalog.json의 penpot.oidc_client:

{
  "clientId": "penpot",
  "name": "Penpot OIDC Identity",
  "protocol": "openid-connect",
  "publicClient": false,
  "standardFlowEnabled": true,
  "directAccessGrantsEnabled": false,
  "serviceAccountsEnabled": true,
  "secret": "${FRACTALOPS_PENPOT_OAUTH_CLIENT_SECRET}",
  "redirectUris": ["${FRACTALOPS_PENPOT_URL}/api/auth/oidc/callback"],
  "webOrigins": ["${FRACTALOPS_PENPOT_URL}"],
  "mapperConfig": {
    "emailClaim": "email",
    "groupsClaim": "groups",
    "usernameClaim": "preferred_username"
  }
}

${FRACTALOPS_PENPOT_URL} / ${FRACTALOPS_PENPOT_OAUTH_CLIENT_SECRET}는 런타임에 resolve_env_or_secret로 해석된다(env -> OpenBao). 절대 하드코딩하지 않는다.

connector / service profile (토폴로지 실값)

# connector_inventory
- id: penpot
  mode: poll
  endpoint: https://penpot.yamon.io
  api_internal_url: http://penpot.penpot.svc.cluster.local:8080
  managed_by: fractalops

# service_profiles.penpot
penpot:
  namespace: penpot
  service: penpot
  port: 8080

mode: poll — Penpot은 표준 SCIM이 없으므로 access sync는 native RPC를 증분 폴링한다.

필수 기능

• FractalOps launch grant 기반 접근.
• 사용자/팀/프로젝트 매핑 정책을 명시한다(project_team_api 투영).
• 캐시/리다이렉트 이슈를 운영 플랜에 포함한다.
• Penpot access sync는 최신 native RPC 경로 /api/main/methods/*와 FRACTALOPS_PENPOT_API_URL / FRACTALOPS_PENPOT_API_TOKEN 계약을 사용한다.
• launch 전에 IDP profile(email/firstName/lastName)을 자동 보정한다 (FRACTALOPS_PORTAL_IDP_PROFILE_ENFORCE_SOLUTIONS 대상).

검증

• 접근 권한 없는 사용자는 차단된다.
• 권한 있는 사용자는 포털 -> Penpot 진입에 성공한다.
• E2E 증거: FO-E2E-006 (Portal -> Penpot Launch, PASS — 팀 생성/프로젝트 화면 진입). (MCP E2E 시나리오 참고)