배포 플랜 크로스 사이트 권한 부여 사용 설명서¶

이 문서는 배포 플랜 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¶

frontApiServerUrlPrefixFormat은 현재 Studio front API의 외부에서 액세스 가능한 기본 URL입니다. 예:

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

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의 일회성 인증 코드 유효 기간, 단위: 초
`issuer`	JWS `iss` / `aud` 검증 주체, 기본값 `"{}"`는 `baseUrl` 사용을 의미
`baseUrl`	이 사이트의 다른 사이트에서 액세스 가능한 front API 기본 URL, 기본값은 `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은 현재 사이트의 서명 확인 공개 키입니다.
활성 개인 키, 과거 공개 키 및 current_kid는 버전 관리에 포함되어서는 안 됩니다.

서비스 업그레이드 후에는 백그라운드 업그레이드 스크립트를 통해 첫 번째 인증서 세트를 초기화해야 합니다. 키를 순환(roll)해야 하는 경우, 이전 서명이 여전히 검증될 수 있도록 과거 공개 키를 유지해야 합니다.

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이 존재하는지.
실행 중인 프로세스에 인증서 디렉터리와 키 파일을 읽을 권한이 있는지.

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