# 조직도 임베딩 토큰 설계

## 목적

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

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

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

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

### 권장 API

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

```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 관리 화면에서 외부 서비스별 임베딩 클라이언트를 등록하고, 각 서비스에 장기 토큰 또는 회전 가능한 토큰 세트를 발급합니다.

### 권장 모델

```json
{
  "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

```http
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은 다음 형태를 기준으로 확장합니다.

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

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