baron-sso/orgfront/docs/orgchart-embedding-token-design.md

조직도 임베딩 토큰 설계

목적

조직도 임베딩 검증 화면은 외부 서비스가 Baron OrgChart의 조직 선택기 또는 조직도 데이터를 안전하게 사용할 수 있는지를 확인하는 도구입니다. 토큰 설계는 다음 두 가지 요구를 동시에 다룹니다.

• 최상위 테넌트 권한 범위에 맞춰 조직도 접근 토큰을 발급한다.
• 특정 서비스가 장기간 안정적으로 임베딩할 수 있도록 서비스 전용 토큰을 생성하고 갱신한다.

방식 A: 최상위 테넌트 권한 기반 토큰

이 방식은 로그인한 사용자의 현재 권한을 기준으로 단기 공유 토큰을 발급합니다. 관리자가 COMPANY_GROUP 또는 최상위 테넌트 범위를 선택하면, 서버는 사용자가 해당 범위를 볼 수 있는지 확인한 뒤 제한된 수명의 토큰을 반환합니다.

권장 API

POST /v1/orgchart/embed-tokens
Authorization: Bearer <access_token>
X-Tenant-ID: <current-tenant-id>
Content-Type: application/json

{
  "scopeType": "tenant_root",
  "rootTenantId": "group-hmac",
  "allowedModes": ["single", "multiple"],
  "allowedSelectableTypes": ["tenant", "user", "both"],
  "expiresInSeconds": 3600
}

서버 검증

• 요청자는 rootTenantId 또는 그 상위 범위를 관리할 수 있어야 합니다.
• 토큰에는 rootTenantId, 허용 선택 모드, 허용 선택 대상, 만료 시각을 포함합니다.
• 토큰은 서버 저장형 opaque token을 우선 권장합니다. 즉시 폐기와 감사 로그 추적이 쉽기 때문입니다.
• JWT를 사용할 경우 jti를 저장해 폐기 목록을 운영해야 합니다.

장점

• 현재 관리자 권한 모델과 자연스럽게 연결됩니다.
• 단기 검증, 데모, 운영자 테스트에 적합합니다.
• 토큰 범위가 명확해 권한 사고 범위를 줄일 수 있습니다.

한계

• 서비스가 장기간 임베딩하려면 사용자가 주기적으로 재발급해야 합니다.
• 외부 서비스 단위의 소유자, 회전 주기, 폐기 정책을 별도로 관리하기 어렵습니다.

방식 B: 특정 서비스용 토큰 생성 및 갱신

이 방식은 Baron Admin 또는 OrgFront 관리 화면에서 외부 서비스별 임베딩 클라이언트를 등록하고, 각 서비스에 장기 토큰 또는 회전 가능한 토큰 세트를 발급합니다.

권장 모델

{
  "id": "embed-client-001",
  "serviceName": "crm-dashboard",
  "ownerTenantId": "group-hmac",
  "rootTenantId": "company-baron",
  "allowedOrigins": ["https://crm.example.com"],
  "allowedModes": ["single", "multiple"],
  "allowedSelectableTypes": ["user"],
  "status": "active",
  "expiresAt": "2026-07-31T00:00:00.000Z",
  "lastRotatedAt": "2026-04-29T00:00:00.000Z"
}

권장 API

POST /v1/admin/orgchart/embed-clients
GET /v1/admin/orgchart/embed-clients
POST /v1/admin/orgchart/embed-clients/{clientId}/rotate-token
POST /v1/admin/orgchart/embed-clients/{clientId}/revoke
GET /v1/public/orgchart/embed-config?token=<embed-token>

서버 검증

• 서비스 토큰은 특정 rootTenantId 이하 데이터에만 접근할 수 있어야 합니다.
• allowedOrigins가 설정된 경우 Origin 헤더를 검증합니다.
• 토큰 회전 시 기존 토큰과 신규 토큰이 함께 유효한 grace period를 짧게 둘 수 있습니다.
• 모든 생성, 갱신, 폐기, 사용 이벤트는 감사 로그에 남깁니다.
• 토큰 원문은 최초 생성 또는 회전 직후에만 보여주고, 서버에는 해시만 저장합니다.

장점

• 외부 서비스별 접근 범위, 만료, 회전, 폐기 정책을 독립적으로 관리할 수 있습니다.
• 운영 환경의 장기 임베딩에 적합합니다.
• 감사 로그와 장애 대응이 명확합니다.

한계

• 별도 관리 화면과 백엔드 저장 모델이 필요합니다.
• 토큰 회전 정책, Origin 검증, 만료 알림 등 운영 기능의 설계 범위가 커집니다.

권장 적용 순서

1. 먼저 방식 A를 구현해 임베딩 검증 화면에서 최상위 테넌트 권한 기반 단기 토큰을 발급합니다.
2. 토큰 payload와 감사 로그 이벤트 스키마를 방식 B에서도 재사용할 수 있게 고정합니다.
3. 외부 서비스 운영 요구가 확정되면 방식 B의 embed client 관리 API와 화면을 추가합니다.
4. 방식 B 도입 후에도 방식 A는 관리자 테스트용 단기 토큰 발급 기능으로 유지합니다.

프론트엔드 반영 방향

임베딩 검증 화면은 현재 선택 모드와 선택 대상 조합을 바꿔 iframe을 갱신합니다. 토큰 기능이 추가되면 다음 값을 함께 표시해야 합니다.

• 발급 주체: 현재 사용자 또는 서비스 클라이언트
• 접근 루트: rootTenantId
• 허용 Origin
• 허용 선택 모드: single, multiple
• 허용 선택 대상: tenant, user, both
• 만료 시각과 갱신 가능 여부

iframe URL은 다음 형태를 기준으로 확장합니다.

/embed/picker?token=<embed-token>&mode=multiple&select=both

서버는 토큰의 허용 범위와 URL query가 충돌할 경우 더 좁은 범위를 적용하거나 요청을 거절해야 합니다.