Embedded Admin

명시된 호출자 환경에서만 사용하세요. 먼저 자격 증명을 설정하세요. 패키지 surface는 SDK README가 소유합니다.

Embedded Admin App

필수 제품 기능이 아니라 tenant별 전용 관리 UI를 Console 안에 둘 때 embedded admin app을 사용합니다. 현재 표면은 tenant당 binding 하나를 지원합니다.

import { receiveEmbeddedAdminSession } from '@01.software/sdk/embedded-admin'

// Browser only. Forward the receipt to your own backend over HTTPS.
export async function receiveSession(consoleOrigin: string) {
  const { requestId, token } = await receiveEmbeddedAdminSession({
    consoleOrigin,
  })
  return { requestId, token }
}

import { verifyEmbeddedAdminSession } from '@01.software/sdk/embedded-admin/server'

// Trusted server only; destination and consoleOrigin are pinned app configuration.
export async function verifySession(
  consoleOrigin: string,
  destination: string,
  receipt: { requestId: string; token: string },
) {
  return verifyEmbeddedAdminSession({
    channelId: receipt.requestId,
    consoleOrigin,
    destination,
    token: receipt.token,
  })
}

iframe은 receiveEmbeddedAdminSession({ consoleOrigin })을 한 번 호출하고, 반환된 requestId와 token을 자기 backend로 즉시 전달합니다. Backend는 app-local session을 만들기 전에 verifyEmbeddedAdminSession({ channelId: requestId, consoleOrigin, destination, token })을 호출합니다. 두 origin을 정확히 고정하고 assertion을 저장·로그하거나 Console API authorization으로 사용하지 않습니다.

Binding 관리는 operator control-plane 작업이므로 public SDK mutation facade로 노출하지 않습니다. Tenant admin은 user PAT와 01 embedded-app CLI를 사용합니다. Loopback HTTP는 기본적으로 거부하며 non-production fixture만 allowLoopbackHttp: true로 명시적으로 허용할 수 있습니다.

--allowed-roles 또는 관리 PATCH의 allowedRoles를 생략하면 기존 실행 정책을 유지합니다. 빈 배열이나 viewer 전용 정책도 유지하며, 새 미설정 정책에만 tenant-admin 기본값을 적용합니다. 역할 배열을 명시할 때만 기존 정책을 변경합니다. 성공 응답은 저장된 역할을 표시하고, 역할 옵션 없는 로컬 dry-run은 해당 필드를 생략합니다.

Assertion은 operator identity와 tenant context만 증명합니다. Tenant data에는 별도의 server-held credential과 앱 자체 authorization policy를 사용합니다.

verifier의 기본 허용 역할은 super-admin과 tenant-admin뿐입니다. editor나 viewer를 허용하려면 binding allowedRoles와 수신자 서버의 신뢰할 수 있는 allowedRoles 옵션에 정확한 역할이 모두 포함되어야 합니다. 예를 들어 수신자는 allowedRoles: ['super-admin', 'tenant-admin', 'tenant-viewer']를 지정합니다. 허용목록은 브라우저 입력에서 받지 마세요. 비관리자는 실행 화면만 받으며 binding 설정과 다른 관리자 설정의 권한은 그대로 유지됩니다.

수신자 서버는 검증한 tenant_role과 operator_id로 앱 기능별 권한을 강제해야 합니다. 앱의 서버 자격증명이 운영자보다 강한 권한을 가질 수 있으므로 버튼 숨김만으로 인가하지 마세요. viewer의 직접 플랫폼 mutation 거부는 유지됩니다. assertion의 60초 만료가 외부 앱 세션을 해지하지는 않습니다. 수신자가 세션 만료, 인가 재검사, 해지 정책을 별도로 구현해야 합니다.

다음 액션

• SDK
• Webhooks