배포 플랜 교차 사이트 권한 부여 사용 안내¶

이 문서에서는 배포 플랜 Studio에서 새 버전 교차 사이트 권한 부여 기능을 사용하는 방법을 설명합니다. 이 기능은 두 사이트 간에 워크스페이스 데이터 권한 부여 관계를 설정하는 데 사용됩니다. 권한 부여 측이 권한 부여 메타를 생성하면, 권한 부여를 받는 측이 이를 가져온 후 인증과 이후 동기화를 능동적으로 수행합니다.

사용 전제 조건¶

배포 플랜 서비스는 먼저 2026-06-03 릴리스 버전 이상으로 업그레이드해야 이 문서에서 설명하는 새 버전 사이트 간 권한 부여 방식을 지원합니다.
권한 부여 측과 권한 부여를 받는 측 모두 CrossSiteGrantCfg 사이트 자격 증명 구성과 교차 사이트 인증서 초기화를 완료해야 합니다.
권한 부여 측이 권한 부여 패키지를 생성하기 전에 현재 서비스를 다른 사이트에서 frontApiServerUrlPrefixFormat 또는 CrossSiteGrantCfg.baseUrl을 통해 액세스할 수 있는지 확인해야 합니다.
권한 부여를 받는 측이 권한 부여 패키지를 가져온 후 권한 부여 측 사이트에 능동적으로 액세스하여 인증과 동기화를 수행합니다. 권한 부여 측은 권한 부여를 받는 측에 능동적으로 액세스하지 않습니다.
무료 플랜 워크스페이스는 이 기능을 지원하지 않습니다.

사용 흐름¶

1. 권한 부여 측에서 권한 부여 메타 생성¶

권한 부여 측 워크스페이스에서 교차 사이트 권한 부여 메타 생성 API를 호출하고 권한 부여를 받는 측 워크스페이스 UUID, 권한 부여 데이터 유형, 인덱스 및 필터 조건을 전달합니다.

API는 권한 부여 측에 pending 레코드를 생성하고 전체 메타를 반환합니다. 호출자는 전체 메타를 권한 부여를 받는 측에 전달하여 가져오도록 해야 합니다. 이 단계에서는 권한 부여를 받는 측 사이트에 능동적으로 액세스하지 않습니다.

2. 권한 부여를 받는 측에서 권한 부여 메타 가져오기¶

권한 부여를 받는 측 워크스페이스에서 교차 사이트 권한 부여 메타 가져오기 API를 호출하고 권한 부여 측이 생성한 전체 메타를 전달합니다.

가져올 때 백엔드는 대상 워크스페이스 검증, 메타 서명 검증, 사이트 관계 검증을 수행하고 권한 부여 측 사이트에 능동적으로 액세스하여 인증을 완료합니다. 인증에 성공하면 권한 부여를 받는 측 로컬에 mirror 권한 부여 레코드가 생성됩니다.

3. 이후 관리¶

권한 부여 레코드가 생성된 후 이후 업무 관리는 계속 기존 크로스 워크스페이스 권한 부여 API를 사용합니다:

/wksp_share/list를 통해 권한 부여 레코드를 조회합니다.
/wksp_share/<uuid>/modify를 통해 권한 부여 범위를 수정합니다.
/wksp_share/delete를 통해 권한 부여를 삭제하거나 취소합니다.

권한 부여 측이 권한 부여 사실의 원본입니다. 권한 부여를 받는 측의 mirror 레코드는 로컬 표시, 워크스페이스 선택기, 권한 부여 검증 및 DQL 쿼리에 사용되며 상태는 동기화 작업을 통해 점차 수렴됩니다.

배포 플랜 구성¶

구성 진입점과 적용 방식¶

이 섹션의 frontApiServerUrlPrefixFormat, CrossSiteGrantCfg, CrossSiteGrantMirrorSyncSet, AllSiteBaseUrls는 모두 Studio 백엔드 서비스 구성 파일의 최상위 구성 항목이며, Guance 콘솔이나 워크스페이스에서 구성하는 항목이 아닙니다.

Launcher로 배포된 환경은 다음 단계에 따라 수정합니다:

Launcher에 로그인하여 오른쪽 상단의 애플리케이션 구성 수정 페이지로 이동합니다.
Namespace가 forethought-core이고 구성 이름이 core인 구성 항목을 찾아 구성 수정을 선택합니다. 애플리케이션 서비스 구성 항목 매뉴얼에서는 이 이름을 Core로 표기하지만, Launcher의 현재 페이지에는 소문자 core로 표시됩니다.
core의 YAML 최상위에 이 섹션의 구성을 추가하거나 수정합니다. frontApiServerUrlPrefixFormat과 CrossSiteGrantCfg는 같은 레벨에 유지해야 하며, CrossSiteGrantCfg나 다른 구성 항목 내부에 넣지 마세요.
저장할 때 구성 수정 후 관련 서비스 자동 재시작을 선택한 후 수정을 확인합니다. Studio는 프로세스 시작 시 이 구성을 읽으므로 재시작되지 않은 프로세스는 새 값을 사용하지 않습니다.

전체 Launcher 작업 및 구성 위치 확인 방법은 애플리케이션 서비스 구성 항목 매뉴얼 - Studio 백엔드 서비스를 참조하세요.

설치 프로그램의 구성 매핑은 다음과 같습니다. 일반적으로 Kubernetes를 직접 조작할 필요는 없습니다:

항목	값
Kubernetes Namespace	`forethought-core`
Launcher 구성 이름	`core`(애플리케이션 서비스 구성 항목 매뉴얼에는 `Core`로 표기)
Kubernetes ConfigMap	`core`
ConfigMap 데이터 키	`config.yaml`
컨테이너 내 마운트 경로	`/config/cloudcare-forethought-backend/config/config.yaml`

참고: 컨테이너 내 config.yaml은 ConfigMap 마운트에서 가져옵니다. Pod에 직접 들어가 수정해도 지속 가능한 구성이 되지 않으며, Pod가 재생성되면 유실됩니다. Launcher를 통해 core를 수정하세요. 환경이 운영 시스템에서 Kubernetes를 직접 관리하는 경우 forethought-core Namespace의 core ConfigMap을 업데이트하고 core/config.yaml을 마운트한 모든 워크로드를 롤링 재시작해야 하며, front-backend만 재시작해서는 안 됩니다. 실제 범위는 현재 설치 프로그램의 core 연결 서비스 목록을 기준으로 하며, 일반적으로 front-backend, open-api, inner, management-backend, core-worker*, core-worker-beat, ai-api, external-api, snapshot-server가 포함됩니다.

구성 계층 예시:

# core / config.yaml 최상위
frontApiServerUrlPrefixFormat: "https://studio.example.com"

CrossSiteGrantCfg:
  # 전체 구성 및 기본값은 아래 참조
  baseUrl: ""

여기서 frontApiServerUrlPrefixFormat에는 현재 사이트의 Studio front API를 상대 사이트에서 액세스할 수 있는 실제 주소를 입력해야 합니다. 현재 환경이 플랫폼에서 내려준 사이트 주소 구성을 사용하는 경우 그중 console_api 값을 사용하고, 선택한 구성이 Guance 및 현재 사이트에 해당하는지 확인하세요. 사용자 지정 도메인 환경에서는 실제로 외부에 노출되는 front API 루트 주소를 입력합니다.

이전 버전에서 업그레이드하면 설치 프로그램이 frontApiServerUrlPrefixFormat을 core의 업데이트 대기 구성으로 표시합니다. 여기의 중국어 안내는 단순한 자리 표시자 설명이므로 위의 실제 주소로 반드시 교체한 뒤 저장해야 하며, 그대로 구성 값으로 사용할 수 없습니다.

CrossSiteGrantCfg의 네 가지 액세스 스위치에는 기본값이 있습니다. issuer, baseUrl, jwksUri는 사용자 지정하지 않으면 frontApiServerUrlPrefixFormat에서 파생되므로 일반적으로 특정 주소로 변경할 필요가 없습니다.

certificateDir는 단순히 인증서 디렉터리 경로일 뿐이며, 인증서 내용을 core에 작성해야 한다는 의미는 아닙니다. 기본 상대 경로는 실제로 컨테이너 내 /config/cloudcare-forethought-backend/sysconfig/cross_site_certificates에 해당하며, 이 디렉터리는 Studio의 공유 ft-sysconfig 스토리지에서 제공됩니다. 인증서는 아래 "교차 사이트 인증서" 요구 사항에 따라 초기화해야 합니다.

frontApiServerUrlPrefixFormat¶

frontApiServerUrlPrefixFormat은 현재 Studio front API의 외부 액세스 가능 루트 주소입니다. 예:

frontApiServerUrlPrefixFormat: "https://studio.example.com"

CrossSiteGrantCfg.baseUrl, issuer 또는 jwksUri를 사용자 지정으로 재정의하지 않은 경우 시스템은 이 주소를 기반으로 교차 사이트 권한 부여 사이트 자격 증명을 파생합니다.

CrossSiteGrantCfg¶

CrossSiteGrantCfg는 교차 사이트 프로토콜 기능, 사이트 자격 증명 및 인증서 로딩을 제어합니다.

CrossSiteGrantCfg:
  sameOrgAccessEnable: true
  sameOrgBeAccessedEnable: true
  externalOrgAccessEnable: true
  externalOrgBeAccessedEnable: true
  tempAuthCodeTTL: 1800
  issuer: "{}"
  baseUrl: ""
  jwksUri: "{}/api/v1/workspace_data/.well-known/cross-site-jwks.json"
  certificateDir: sysconfig/cross_site_certificates

구성 항목 설명:

구성 항목	설명
`sameOrgAccessEnable`	이 사이트가 액세스 주체일 때 동일 조직의 교차 사이트 권한 부여 데이터 액세스를 허용할지 여부
`sameOrgBeAccessedEnable`	이 사이트가 액세스 대상일 때 동일 조직 사이트의 이 사이트 권한 부여 데이터 액세스를 허용할지 여부
`externalOrgAccessEnable`	이 사이트가 액세스 주체일 때 다른 조직의 교차 사이트 권한 부여 데이터 액세스를 허용할지 여부
`externalOrgBeAccessedEnable`	이 사이트가 액세스 대상일 때 다른 조직 사이트의 이 사이트 권한 부여 데이터 액세스를 허용할지 여부
`tempAuthCodeTTL`	메타 내 일회성 인증 code의 유효 기간(초)
`issuer`	JWS `iss`/`aud` 검증 주체, 기본 `"{}"`는 `baseUrl` 사용을 의미
`baseUrl`	이 사이트를 다른 사이트에서 액세스할 수 있는 front API 루트 주소, 기본은 `frontApiServerUrlPrefixFormat`에서 파생
`jwksUri`	이 사이트의 JWKS 공개 키 발견 주소, 기본은 `baseUrl`에서 파생
`certificateDir`	교차 사이트 권한 부여 인증서 디렉터리

사이트 내 크로스 워크스페이스 권한 부여는 위의 교차 사이트 액세스 스위치의 영향을 받지 않습니다.

교차 사이트 인증서¶

certificateDir의 기본값은 sysconfig/cross_site_certificates이며 디렉터리 구조는 다음과 같습니다:

sysconfig/cross_site_certificates/
  current_kid
  private/<kid>.pem
  public/<kid>.pem

인증서 파일은 JWS 서명 및 JWKS 공개 키 발견에 사용됩니다:

current_kid는 현재 active key를 가리킵니다.
private/<kid>.pem은 현재 사이트의 서명 개인 키입니다.
public/<kid>.pem은 현재 사이트의 서명 검증 공개 키입니다.
active 개인 키, 이력 공개 키 및 current_kid는 버전 관리에 포함하면 안 됩니다.

서비스 업그레이드 후 백그라운드 업그레이드 스크립트를 통해 첫 번째 인증서 세트를 초기화해야 합니다. key를 롤링해야 하는 경우 이전 서명도 계속 검증할 수 있도록 이력 public key를 보존해야 합니다.

CrossSiteGrantMirrorSyncSet¶

권한 부여를 받는 측의 mirror 권한 부여 레코드는 예약 작업을 통해 권한 부여 측의 최신 상태를 능동적으로 동기화합니다.

CrossSiteGrantMirrorSyncSet:
  isOpen: true
  staleSeconds: 3600
  batchSize: 200
  lockExpireSeconds: 1800
  crontabSet:
    minute: "*/10"

이 구성은 mirror 동기화에만 영향을 주며 권한 부여 측의 사실 레코드에는 영향을 주지 않습니다.

동일 조직 사이트 구성¶

동일 조직 교차 사이트 권한 부여는 AllSiteBaseUrls.<brandKey>를 사용하여 공식 사이트 front API 주소를 확인합니다. 상대 사이트는 공식 사이트 컬렉션에 존재해야 하며, 메타의 baseUrl/jwksUri는 공식 주소와 일치해야 합니다.

다른 조직 또는 외부 배포 플랜 사이트는 AllSiteBaseUrls로 주소를 파생하는 데 의존하지 말고, 메타와 mirror 레코드의 baseUrl, issuer, jwksUri 및 공개 키 자격 증명을 사용하여 검증을 완료해야 합니다.

자주 묻는 질문¶

현재 사이트 자격 증명 구성 불완전 안내¶

확인 사항:

frontApiServerUrlPrefixFormat이 외부 액세스 가능 주소로 구성되었는지 여부.
CrossSiteGrantCfg.baseUrl, issuer, jwksUri가 비어 있거나 형식이 잘못되었는지 여부.
certificateDir 아래에 current_kid, private/<kid>.pem, public/<kid>.pem이 존재하는지 여부.
실행 중인 프로세스에 인증서 디렉터리와 key 파일을 읽을 수 있는 권한이 있는지 여부.

권한 부여 패키지 가져오기 실패¶