배포 플랜 사이트 간 권한 부여 사용 안내¶
이 문서는 배포 플랜 Studio에서 새 버전의 사이트 간 권한 부여 기능을 사용하는 방법을 설명합니다. 이 기능은 두 사이트 간에 워크스페이스 데이터 권한 부여 관계를 수립하는 데 사용되며, 권한 부여 측이 권한 부여 meta를 생성하면 권한 부여 대상 측이 이를 가져온 후 인증 및 이후 동기화를 직접 완료합니다.
사용 전제 조건¶
- 배포 플랜 서비스는 최소 2026-06-03 릴리스 버전으로 업그레이드되어야 이 문서에서 설명하는 새 버전 사이트 간 권한 부여 방식을 지원합니다.
- 권한 부여 측과 권한 부여 대상 측 모두
CrossSiteGrantCfg사이트 ID 구성과 사이트 간 인증서 초기화를 완료해야 합니다. - 권한 부여 측은 권한 부여 패키지를 생성하기 전에 현재 서비스를 다른 사이트에서
frontApiServerUrlPrefixFormat또는CrossSiteGrantCfg.baseUrl을 통해 액세스할 수 있는지 확인해야 합니다. - 권한 부여 대상 측은 권한 부여 패키지를 가져온 후 권한 부여 측 사이트에 직접 액세스하여 인증과 동기화를 완료합니다. 권한 부여 측은 권한 부여 대상 측에 직접 액세스하지 않습니다.
- 무료 플랜 워크스페이스는 이 기능을 지원하지 않습니다.
사용 절차¶
1. 권한 부여 측에서 권한 부여 meta 생성¶
권한 부여 측 워크스페이스에서 사이트 간 권한 부여 meta 생성 API를 호출하고 권한 부여 대상 측 워크스페이스 UUID, 권한 부여 데이터 유형, 인덱스 및 필터 조건을 전달합니다.
이 API는 권한 부여 측에 pending 레코드를 생성하고 전체 meta를 반환합니다. 호출자는 전체 meta를 권한 부여 대상 측에 전달하여 가져오도록 해야 합니다. 이 단계에서는 권한 부여 대상 측 사이트에 직접 액세스하지 않습니다.
2. 권한 부여 대상 측에서 권한 부여 meta 가져오기¶
권한 부여 대상 측 워크스페이스에서 사이트 간 권한 부여 meta 가져오기 API를 호출하고 권한 부여 측이 생성한 전체 meta를 전달합니다.
가져오기 시 백엔드는 대상 워크스페이스 검증, meta 서명 검증, 사이트 관계 검증을 수행하고 권한 부여 측 사이트에 직접 액세스하여 인증을 완료합니다. 인증에 성공하면 권한 부여 대상 측 로컬에 mirror 권한 부여 레코드가 생성됩니다.
3. 이후 관리¶
권한 부여 레코드가 생성된 후에도 이후 비즈니스 관리는 기존 워크스페이스 간 권한 부여 API를 계속 사용합니다.
/wksp_share/list를 통해 권한 부여 레코드를 조회합니다./wksp_share/<uuid>/modify를 통해 권한 부여 범위를 수정합니다./wksp_share/delete를 통해 권한 부여를 삭제하거나 철회합니다.
권한 부여 측은 권한 부여의 사실 원천(source of truth)입니다. 권한 부여 대상 측의 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-coreNamespace의coreConfigMap을 업데이트하고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의 외부에서 접근 가능한 루트 주소입니다. 예를 들면 다음과 같습니다.
CrossSiteGrantCfg.baseUrl, issuer, jwksUri를 사용자 정의로 재정의하지 않은 경우 시스템은 이 주소를 기반으로 사이트 간 권한 부여 사이트 ID를 파생합니다.
CrossSiteGrantCfg¶
CrossSiteGrantCfg는 사이트 간 프로토콜 기능, 사이트 ID 및 인증서 로드를 제어합니다.
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 |
meta에 포함된 일회용 인증 code의 유효 기간(초) |
issuer |
JWS iss / aud 검증 주체. 기본값 "{}"은 baseUrl을 사용함을 의미합니다. |
baseUrl |
이 사이트를 다른 사이트에서 액세스할 수 있는 front API 루트 주소. 기본값은 frontApiServerUrlPrefixFormat에서 파생됩니다. |
jwksUri |
이 사이트의 JWKS 공개 키 발견 주소. 기본값은 baseUrl에서 파생됩니다. |
certificateDir |
사이트 간 권한 부여 인증서 디렉터리 |
사이트 내 워크스페이스 간 권한 부여는 위의 사이트 간 액세스 스위치의 영향을 받지 않습니다.
사이트 간 인증서¶
certificateDir의 기본값은 sysconfig/cross_site_certificates이며 디렉터리 구조는 다음과 같습니다.
인증서 파일은 JWS 서명 및 JWKS 공개 키 발견에 사용됩니다.
current_kid는 현재 활성 키를 가리킵니다.private/<kid>.pem은 현재 사이트의 서명 개인 키입니다.public/<kid>.pem은 현재 사이트의 서명 검증 공개 키입니다.- 활성 개인 키, 이력 공개 키 및
current_kid는 버전 관리에 포함해서는 안 됩니다.
서비스 업그레이드 후 백엔드 업그레이드 스크립트로 첫 번째 인증서 세트를 초기화해야 합니다. 키를 순환(rollover)해야 하는 경우 기존 서명을 계속 검증할 수 있도록 이전 public key를 보존해야 합니다.
CrossSiteGrantMirrorSyncSet¶
권한 부여 대상 측의 mirror 권한 부여 레코드는 예약 작업을 통해 권한 부여 측의 최신 상태를 직접 동기화합니다.
CrossSiteGrantMirrorSyncSet:
isOpen: true
staleSeconds: 3600
batchSize: 200
lockExpireSeconds: 1800
crontabSet:
minute: "*/10"
이 구성은 mirror 동기화에만 영향을 미치며 권한 부여 측의 사실 레코드에는 영향을 미치지 않습니다.
동일 조직 사이트 구성¶
동일 조직 사이트 간 권한 부여는 AllSiteBaseUrls.<brandKey>를 사용하여 공식 사이트의 front API 주소를 확인합니다. 상대 사이트는 공식 사이트 집합에 존재해야 하며, meta의 baseUrl / jwksUri는 공식 주소와 일치해야 합니다.
다른 조직 또는 외부 배포 플랜 사이트는 AllSiteBaseUrls에 의존해 주소를 파생해서는 안 되며, meta 및 mirror 레코드의 baseUrl, issuer, jwksUri와 공개 키 ID를 사용하여 검증을 완료해야 합니다.
자주 묻는 질문¶
현재 사이트 ID 구성이 불완전하다는 메시지가 표시되는 경우¶
다음을 확인합니다.
frontApiServerUrlPrefixFormat이 외부에서 접근 가능한 주소로 구성되었는지 확인합니다.CrossSiteGrantCfg.baseUrl,issuer,jwksUri가 비어 있거나 형식이 잘못되었는지 확인합니다.certificateDir아래에current_kid,private/<kid>.pem,public/<kid>.pem이 존재하는지 확인합니다.- 실행 중인 프로세스에 인증서 디렉터리와 key 파일을 읽을 수 있는 권한이 있는지 확인합니다.
권한 부여 패키지 가져오기 실패¶
다음을 확인합니다.
- 권한 부여 대상 측 워크스페이스가 meta의
targetWorkspaceUUID와 일치하는지 확인합니다. - 권한 부여 패키지가 만료되었는지 확인합니다.
- 권한 부여 측 사이트를 권한 부여 대상 측에서 접근할 수 있는지 확인합니다.
- 양쪽 모두 최소 2026-06-03 릴리스 버전으로 업그레이드되었는지 확인합니다.
- 동일 조직 사이트의
AllSiteBaseUrls가 올바르게 구성되었는지 확인합니다. - 다른 조직 사이트 간 스위치가 현재 방향으로의 접근을 허용하는지 확인합니다.
mirror 레코드가 제때 업데이트되지 않는 경우¶
mirror 레코드는 권한 부여 대상 측에서 직접 동기화합니다. CrossSiteGrantMirrorSyncSet.isOpen, 예약 작업 구성, 권한 부여 측 사이트 연결성, 동기화 작업 로그를 확인하면 됩니다.