Deployment Plan Cross-Site Authorization Usage Instructions¶

This document explains how to use the new version of cross-site authorization capability in Deployment Plan Studio. This capability is used to establish a workspace data authorization relationship between two sites. The authorizing site generates authorization meta, and the authorized site imports it and actively completes authentication and subsequent synchronization.

Prerequisites¶

• The Deployment Plan service must be upgraded to at least the version released on 2026-06-03 to support the new cross-site authorization method described in this document.
• Both the authorizing site and the authorized site need to complete the CrossSiteGrantCfg site identity configuration and cross-site certificate initialization.
• Before generating the authorization package, the authorizing site needs to confirm that its current service can be accessed by other sites via frontApiServerUrlPrefixFormat or CrossSiteGrantCfg.baseUrl.
• After importing the authorization package, the authorized site will actively access the authorizing site to complete authentication and synchronization. The authorizing site will not actively access the authorized site.
• Free Plan workspaces do not support this capability.

Usage Process¶

1. Authorizing Site Generates Authorization Meta¶

Call the Generate Cross-Site Authorization Meta API in the authorizing workspace, passing in the authorized workspace UUID, authorized data types, indexes, and filter conditions.

The API will create a pending record on the authorizing side and return the complete meta. The caller needs to provide the complete meta to the authorized site for import. This step does not actively access the authorized site.

2. Authorized Site Imports Authorization Meta¶

Call the Import Cross-Site Authorization Meta API in the authorized workspace, passing in the complete meta generated by the authorizing site.

During import, the backend will complete target workspace validation, meta signature verification, site relationship validation, and actively access the authorizing site to complete authentication. After successful authentication, a mirror authorization record will be created locally on the authorized side.

3. Subsequent Management¶

After the authorization record is created, subsequent business management still uses the cross-workspace authorization APIs:

• View authorization records via /wksp_share/list.
• Modify authorization scope via /wksp_share/<uuid>/modify.
• Delete or revoke authorization via /wksp_share/delete.

The authorizing site is the source of the authorization fact. The mirror record on the authorized side is used for local display, workspace selector, authorization validation, and DQL queries. Its status will gradually converge through synchronization tasks.

Deployment Plan Configuration¶

frontApiServerUrlPrefixFormat¶

frontApiServerUrlPrefixFormat is the externally accessible root address of the current Studio front API, for example:

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

When CrossSiteGrantCfg.baseUrl, issuer, or jwksUri are not custom overridden, the system will derive the cross-site authorization site identity based on this address.

CrossSiteGrantCfg¶

CrossSiteGrantCfg controls cross-site protocol capability, site identity, and certificate loading.

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

Configuration Item Description:

Cross-workspace authorization within the same site is not affected by the above cross-site access switches.

Cross-Site Certificates¶

certificateDir defaults to sysconfig/cross_site_certificates. The directory structure is as follows:

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

The certificate files are used for JWS signing and JWKS public key discovery:

• current_kid points to the current active key.
• private/<kid>.pem is the current site's signing private key.
• public/<kid>.pem is the current site's verification public key.
• Active private keys, historical public keys, and current_kid must not be included in version control.

After a service upgrade, the initial set of certificates needs to be initialized via a backend upgrade script. If key rotation is required, historical public keys should be retained to ensure old signatures can still be verified.

CrossSiteGrantMirrorSyncSet¶

The mirror authorization records on the authorized side are actively synchronized with the latest status from the authorizing site via scheduled tasks.

CrossSiteGrantMirrorSyncSet:
  isOpen: true
  staleSeconds:我们发现一个错误。请继续翻译。 3600
  batchSize: 200
  lockExpireSeconds: 1800
  crontabSet:
    minute: "*/10"

This configuration only affects mirror synchronization and does not affect the factual records on the authorizing side.

Same Organization Site Configuration¶

Cross-site authorization within the same organization relies on AllSiteBaseUrls.<brandKey> to resolve the official site's front API address. The other site must exist in the official site collection, and the baseUrl / jwksUri in the meta must match the official address.

Sites from different organizations or external Deployment Plan sites should not rely on AllSiteBaseUrls to derive addresses. Instead, they should use the baseUrl, issuer, jwksUri, and public key identity in the meta and mirror records to complete validation.

Common Issues¶

Prompt: Current Site Identity Configuration is Incomplete¶

Check:

• Whether frontApiServerUrlPrefixFormat is configured as an externally accessible address.
• Whether CrossSiteGrantCfg.baseUrl, issuer, jwksUri are empty or incorrectly formatted.
• Whether current_kid, private/<kid>.pem, public/<kid>.pem exist under certificateDir.
• Whether the running process has permission to read the certificate directory and key files.

Failed to Import Authorization Package¶

Check:

• Whether the authorized workspace matches the targetWorkspaceUUID in the meta.
• Whether the authorization package has expired.
• Whether the authorizing site is accessible from the authorized site.
• Whether both sides have been upgraded to at least the version released on 2026-06-03.
• Whether AllSiteBaseUrls is correctly configured for sites within the same organization.
• Whether the cross-site switch for different organizations allows access in the current direction.

Mirror Record Not Updated Timely¶

Mirror records are actively synchronized by the authorized site. Check CrossSiteGrantMirrorSyncSet.isOpen, scheduled task configuration, connectivity to the authorizing site, and synchronization task logs.