forked from baron/baron-sso
126 lines
5.2 KiB
Markdown
126 lines
5.2 KiB
Markdown
# 조직도 임베딩 토큰 설계
|
|
|
|
## 목적
|
|
|
|
조직도 임베딩 검증 화면은 외부 서비스가 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가 충돌할 경우 더 좁은 범위를 적용하거나 요청을 거절해야 합니다.
|