デプロイメントプランのクロスサイト認可使用手順¶

本ドキュメントでは、デプロイメントプランの Studio が新バージョンのクロスサイト認可機能を使用する方法について説明します。この機能は、2 つのサイト間でワークスペースデータの認可関係を確立するために使用され、認可側が認可 meta を生成し、被認可側がインポートした後、能動的に認証とその後の同期を実行します。

前提条件¶

• デプロイメントプランのサービスは、本ドキュメントで説明する新バージョンのサイト間認可方式を利用するには、まず 2026-06-03 リリースバージョン以降にアップグレードする必要があります。
• 認可側と被認可側の両方で、CrossSiteGrantCfg のサイト ID 設定とクロスサイト証明書の初期化を完了する必要があります。
• 認可側が認可パッケージを生成する前に、現在のサービスが他のサイトから frontApiServerUrlPrefixFormat または CrossSiteGrantCfg.baseUrl でアクセス可能であることを確認する必要があります。
• 被認可側は認可パッケージをインポートした後、認可側サイトに能動的にアクセスして認証と同期を実行します。認可側が被認可側に能動的にアクセスすることはありません。
• 無料版のワークスペースではこの機能はサポートされません。

利用手順¶

1. 認可側が認可 meta を生成¶

認可側のワークスペースで クロスサイト認可 meta を生成 インターフェースを呼び出し、被認可側のワークスペース UUID、認可データタイプ、インデックス、フィルター条件を渡します。

このインターフェースは認可側の pending レコードを作成し、完全な meta を返します。呼び出し元は完全な meta を被認可側に渡し、インポートさせる必要があります。この手順では被認可側のサイトに能動的にアクセスしません。

2. 被認可側が認可 meta をインポート¶

被認可側のワークスペースで クロスサイト認可 meta をインポート インターフェースを呼び出し、認可側が生成した完全な meta を渡します。

インポート時に、バックエンドは対象ワークスペースの検証、meta 署名の検証、サイト関係の検証を実行し、認可側サイトに能動的にアクセスして認証を完了します。認証が成功すると、被認可側のローカルに mirror 認可レコードが作成されます。

3. その後の管理¶

認可レコードの作成後、その後の業務管理では引き続きクロスワークスペース認可インターフェースを使用します：

• /wksp_share/list で認可レコードを確認します。
• /wksp_share/<uuid>/modify で認可範囲を変更します。
• /wksp_share/delete で認可を削除または取り消します。

認可側は認可の正本です。被認可側の mirror レコードは、ローカル表示、ワークスペースセレクター、認可検証、DQL クエリに使用され、状態は同期タスクによって徐々に収束します。

デプロイメントプランの設定¶

設定場所と反映方法¶

このセクションの frontApiServerUrlPrefixFormat、CrossSiteGrantCfg、CrossSiteGrantMirrorSyncSet、AllSiteBaseUrls はすべて Studio バックエンドサービスの設定ファイルのトップレベル設定項目であり、Guanceコンソールやワークスペースで設定するものではありません。

Launcher でデプロイされた環境では、次の手順で変更してください：

1. Launcher にログインし、右上隅のアプリケーション設定の変更ページを開きます。
2. Namespace が forethought-core、設定名が core の設定項目を探し、設定の変更にチェックを入れます。アプリケーションサービス設定項目マニュアルではこの名前は Core と記載されていますが、Launcher の現在のページでは小文字の core として表示されます。
3. core の YAML トップレベルにこのセクションの設定を追加または変更します。frontApiServerUrlPrefixFormat と CrossSiteGrantCfg は同じ階層に保つ必要があります。CrossSiteGrantCfg や他の設定項目の内部には配置しないでください。
4. 保存時に設定変更後に関連サービスを自動再起動するにチェックを入れ、変更を確定します。Studio はプロセスの起動時にこの設定を読み込むため、再起動されていないプロセスは新しい値を使用しません。

Launcher の操作と設定の特定方法の詳細は、アプリケーションサービス設定項目マニュアル - Studio バックエンドサービス を参照してください。

インストーラーの設定マッピングは以下のとおりです。通常、Kubernetes を直接操作する必要はありません：

注意: コンテナ内の config.yaml は ConfigMap のマウントに由来します。Pod に直接入って変更しても持続可能な設定にはならず、Pod の再作成後には失われます。Launcher 経由で core を変更してください。環境が運用システムによって Kubernetes を直接管理している場合は、forethought-core Namespace の core ConfigMap を更新し、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 の 4 つのアクセススイッチにはすでにデフォルト値があります。issuer、baseUrl、jwksUri はカスタマイズされていない場合、frontApiServerUrlPrefixFormat から派生するため、通常は具体的なアドレスに変更する必要はありません。

certificateDir は証明書ディレクトリのパスのみを示し、証明書の内容を core に書き込むことを意味するものではありません。デフォルトの相対パスは、実際にはコンテナ内の /config/cloudcare-forethought-backend/sysconfig/cross_site_certificates に対応します。このディレクトリは Studio の共有 ft-sysconfig ストレージに由来します。証明書は引き続き、後述の「クロスサイト証明書」の要件に従って初期化する必要があります。

frontApiServerUrlPrefixFormat¶

frontApiServerUrlPrefixFormat は、現在の Studio front API の外部からアクセス可能なルートアドレスです。例：

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

設定項目の説明：

サイト内のクロスワークスペース認可は、上記のクロスサイトアクセススイッチの影響を受けません。

クロスサイト証明書¶

certificateDir のデフォルトは sysconfig/cross_site_certificates で、ディレクトリ構造は以下のとおりです：

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

証明書ファイルは、JWS 署名と JWKS 公開鍵ディスカバリーに使用されます：

• current_kid は現在のアクティブキーを指します。
• private/<kid>.pem は現在のサイトの署名用秘密鍵です。
• public/<kid>.pem は現在のサイトの署名検証用公開鍵です。
• アクティブな秘密鍵、過去の公開鍵、current_kid はバージョン管理に含めることはできません。

サービスアップグレード後は、バックグラウンドのアップグレードスクリプトによって最初の証明書セットを初期化する必要があります。キーをローテーションする必要がある場合は、過去の公開鍵を保持し、古い署名が引き続き検証可能であることを確認してください。

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 が存在するか。
• 実行中のプロセスに証明書ディレクトリとキーファイルを読み取る権限があるか。

認可パッケージのインポートに失敗する¶

確認事項：

• 被認可側のワークスペースが meta 内の targetWorkspaceUUID と一致しているか。
• 認可パッケージが有効期限切れになっていないか。
• 認可側サイトが被認可側からアクセス可能か。
• 双方が少なくとも 2026-06-03 リリースバージョンにアップグレードされているか。
• 同組織のサイトで AllSiteBaseUrls が正しく設定されているか。
• 異なる組織のクロスサイトスイッチが現在の方向のアクセスを許可しているか。

mirror レコードが適時に更新されない¶

mirror レコードは被認可側によって能動的に同期されます。CrossSiteGrantMirrorSyncSet.isOpen、定期タスクの設定、認可側サイトの接続性、同期タスクのログを確認してください。