Cross-Site Authorization for Deployment Plan¶

This document explains how Studio in the Deployment Plan uses the new cross-site authorization capability. This capability is used to establish a workspace data authorization relationship between two sites. The granting side generates the authorization meta, and the recipient side imports it and then actively completes authentication and subsequent synchronization.

Prerequisites¶

• Deployment Plan services must first be upgraded to at least the 2026-06-03 release to support the new cross-site authorization method described in this document.
• Both the granting side and the recipient side must complete CrossSiteGrantCfg site identity configuration and cross-site certificate initialization.
• Before generating the authorization package, the granting side must confirm that the current service can be accessed by other sites through frontApiServerUrlPrefixFormat or CrossSiteGrantCfg.baseUrl.
• After importing the authorization package, the recipient side actively accesses the granting site to complete authentication and synchronization; the granting side does not actively access the recipient side.
• Free Plan workspaces do not support this capability.

Usage Flow¶

1. The Granting Side Generates the Authorization Meta¶

In the granting workspace, call the Generate Cross-Site Authorization Meta API and pass the recipient workspace UUID, the data type to authorize, the index, and the filter conditions.

The API creates a pending record on the granting side and returns the complete meta. The caller must provide the complete meta to the recipient side for import. This step does not actively access the recipient site.

2. The Recipient Side Imports the Authorization Meta¶

In the recipient workspace, call the Import Cross-Site Authorization Meta API and pass the complete meta generated by the granting side.

During import, the backend validates the target workspace, verifies the meta signature, validates the site relationship, and actively accesses the granting site to complete authentication. After successful authentication, a mirror authorization record is created locally on the recipient 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 the authorization scope via /wksp_share/<uuid>/modify.
• Delete or revoke authorizations via /wksp_share/delete.

The granting side is the source of truth for authorization. Mirror records on the recipient side are used for local display, the workspace selector, authorization validation, and DQL queries, and their status gradually converges through the synchronization tasks.

Deployment Plan Configuration¶

Configuration Entry Point and How Changes Take Effect¶

The frontApiServerUrlPrefixFormat, CrossSiteGrantCfg, CrossSiteGrantMirrorSyncSet, and AllSiteBaseUrls described in this section are top-level configuration items in the Studio backend service configuration file, not items configured in the Guance console or a workspace.

For environments deployed via Launcher, modify the configuration as follows:

1. Log in to Launcher and open Modify Application Configurations in the upper-right corner.
2. Find the configuration item whose Namespace is forethought-core and whose configuration name is core, and select Modify Configuration. The Application Service Configuration Guide writes this name as Core, while the Launcher page displays it as lowercase core.
3. Add or modify this section's configuration at the top level of the core YAML. frontApiServerUrlPrefixFormat and CrossSiteGrantCfg should stay at the same level; do not place frontApiServerUrlPrefixFormat inside CrossSiteGrantCfg or any other configuration item.
4. When saving, select Automatically restart related services after configuration changes, and then confirm the modification. Studio reads this configuration when processes start; processes that have not been restarted will not use the new values.

For the complete Launcher operations and how to locate the configuration, see Application Service Configuration Guide - Studio Backend Service.

The configuration mapping in the installer is as follows; you usually do not need to operate Kubernetes directly:

Note: The config.yaml inside the container comes from the ConfigMap mount. Directly entering a Pod to modify it does not create a persistent configuration, and the changes are lost after the Pod is recreated. Modify core through Launcher instead. If Kubernetes is managed directly by the operations system, update the core ConfigMap under the forethought-core Namespace and perform a rolling restart of all workloads that mount core/config.yaml; do not restart only front-backend. The actual scope is subject to the service list associated with core in the current installer, and usually includes front-backend, open-api, inner, management-backend, core-worker*, core-worker-beat, ai-api, external-api, and snapshot-server.

Example of the configuration hierarchy:

# Top level of core / config.yaml
frontApiServerUrlPrefixFormat: "https://studio.example.com"

CrossSiteGrantCfg:
  # See the complete configuration and default values below
  baseUrl: ""

Here, frontApiServerUrlPrefixFormat must be set to the actual address at which the current site's Studio front API can be accessed by the peer site. If the current environment uses the site address configuration issued by the platform, take the console_api value from it and confirm that the selected configuration corresponds to Guance and the current site. For custom domain environments, enter the actual externally exposed front API root address.

When upgrading from an older version, the installer displays frontApiServerUrlPrefixFormat as a pending configuration update in core. The Chinese prompt in it is only a placeholder; replace it with the actual address described above before saving, and do not use it as the configuration value as-is.

The four access switches in CrossSiteGrantCfg already have default values. When issuer, baseUrl, and jwksUri are not customized, they are derived from frontApiServerUrlPrefixFormat; you usually do not need to change them to specific addresses.

certificateDir is only the certificate directory path; it does not mean that certificate contents should be written into core. The default relative path actually corresponds to /config/cloudcare-forethought-backend/sysconfig/cross_site_certificates inside the container. This directory comes from the shared ft-sysconfig storage of Studio. The certificates still need to be initialized as required by "Cross-Site Certificates" below.

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 customized to override it, the system derives the cross-site authorization site identity based on this address.

CrossSiteGrantCfg¶

CrossSiteGrantCfg controls cross-site protocol capabilities, 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 descriptions:

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

Cross-Site Certificates¶

By default, certificateDir is sysconfig/cross_site_certificates, with the following directory structure:

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 signing private key of the current site.
• public/<kid>.pem is the public key used for signature verification at the current site.
• The active private key, historical public keys, and current_kid must not be committed to version control.

After a service upgrade, the first set of certificates needs to be initialized through the backend upgrade script. If key rotation is needed, retain the historical public keys to ensure that old signatures can still be verified.

CrossSiteGrantMirrorSyncSet¶

Mirror authorization records on the recipient side proactively synchronize the latest status of the granting side through a scheduled task.

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

This configuration only affects mirror synchronization and does not affect the granting side's source-of-truth records.

Same-Organization Site Configuration¶

Same-organization cross-site authorization relies on AllSiteBaseUrls.<brandKey> to resolve the front API addresses of official sites. The peer site must exist in the official site set, and the baseUrl / jwksUri in the meta must match the official addresses.

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

FAQ¶

Current Site Identity Configuration Is Incomplete¶

Check:

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

Importing the Authorization Package Fails¶

Check:

• Whether the recipient workspace matches the targetWorkspaceUUID in the meta.
• Whether the authorization package has expired.
• Whether the granting site is accessible from the recipient side.
• Whether both sides have been upgraded to at least the 2026-06-03 release.
• Whether same-organization sites have correctly configured AllSiteBaseUrls.
• Whether the cross-site switches for different organizations allow access in the current direction.

Mirror Records Are Not Updated in a Timely Manner¶

Mirror records are proactively synchronized by the recipient side. Check CrossSiteGrantMirrorSyncSet.isOpen, the scheduled task configuration, connectivity to the granting site, and the synchronization task logs.