Deployment Plan Cross-Site Authorization Guide¶

This document describes how Studio in the Deployment Plan uses the new cross-site authorization capability. This capability establishes a workspace data authorization relationship between two sites. The grantor generates a grant meta, and after the grantee imports it, the grantee proactively completes authentication and subsequent synchronization.

Prerequisites¶

• The Deployment Plan service must first be upgraded to at least the 2026-06-03 release version before it supports the new cross-site authorization method described in this document.
• Both the grantor and the grantee must complete the CrossSiteGrantCfg site identity configuration and cross-site certificate initialization.
• Before the grantor generates the authorization package, confirm that the current service can be accessed by other sites via frontApiServerUrlPrefixFormat or CrossSiteGrantCfg.baseUrl.
• After the grantee imports the authorization package, the grantee proactively accesses the grantor site to complete authentication and synchronization; the grantor does not proactively access the grantee.
• Free Plan workspaces do not support this capability.

Procedure¶

1. The grantor generates the grant meta¶

In the grantor workspace, call the Generate Cross-Site Grant Meta API and pass in the grantee workspace UUID, authorized data types, indexes, and filter conditions.

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

2. The grantee imports the grant meta¶

In the grantee workspace, call the Import Cross-Site Grant Meta API and pass in the complete meta generated by the grantor.

During import, the backend performs target workspace validation, meta signature validation, and site relationship validation, and proactively accesses the grantor site to complete authentication. After successful authentication, a mirror grant record is created locally on the grantee side.

3. Subsequent management¶

After the grant record is created, subsequent business management continues to use the cross-workspace authorization APIs:

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

The grantor is the source of truth for the authorization. The grantee's mirror records are used for local display, the workspace selector, authorization validation, and DQL queries; their status converges gradually through synchronization tasks.

Deployment Plan Configuration¶

Configuration entry point and how changes take effect¶

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

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

1. Log in to Launcher and open the Modify Application Configuration page in the upper-right corner.
2. Locate the configuration item with Namespace forethought-core and configuration name core, and select Modify Configuration. The Application Service Configuration Item Manual writes this name as Core, while the current Launcher page displays it as lowercase core.
3. Add or modify the configuration in this section at the top level of the core YAML. frontApiServerUrlPrefixFormat and CrossSiteGrantCfg should remain at the same level; do not place them inside CrossSiteGrantCfg or any other configuration item.
4. When saving, select Automatically restart related services after configuration modification, and then confirm the change. Studio reads this configuration at process startup; processes that have not been restarted will not use the new value.

For complete Launcher operations and configuration lookup, see Application Service Configuration Item Manual - Studio Backend Service.

The configuration mapping in the installer is as follows. Normally, you do not need to operate Kubernetes directly:

Note: The config.yaml inside the container comes from the ConfigMap mount. Directly modifying it in the Pod does not create sustainable configuration, and changes will be lost after the Pod is recreated. Modify core through Launcher instead. If the environment manages Kubernetes directly via the operations system, update the core ConfigMap in the forethought-core Namespace and rolling-restart all workloads that mount core/config.yaml; do not restart only front-backend. The actual scope is determined by the service list associated with core in the current installer, and typically 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:

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

CrossSiteGrantCfg:
  # Full configuration and defaults are described 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, use 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 description; you must replace it with the actual address described above before saving. Do not use it as the configuration value as-is.

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

certificateDir is only the certificate directory path and does not mean that certificate content 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 Studio's shared ft-sysconfig storage. Certificates still need to be initialized as required in "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 has no custom override, 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 cross-site access switches described above.

Cross-Site Certificates¶

The 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 verification public key of 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 must be initialized through the backend upgrade script. If keys need to be rotated, keep historical public keys so that old signatures can still be verified.

CrossSiteGrantMirrorSyncSet¶

The grantee's mirror grant records proactively synchronize the latest status from the grantor through 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 grantor's source-of-truth records.

Same-Organization Site Configuration¶

Same-organization cross-site authorization relies on AllSiteBaseUrls.<brandKey> to resolve the front API address 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 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¶

The system reports that the current site identity configuration is incomplete¶

Check the following:

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

Failed to import the authorization package¶

Check the following:

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

Mirror records are not updated in time¶

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