デプロイメントプランのクロスサイト認可利用ガイド¶
この記事では、デプロイメントプランの Studio で新しいバージョンのクロスサイト認可機能を使用する方法について説明します。この機能は、2つのサイト間でワークスペースのデータ認可関係を確立するために使用します。認可元が認可メタを生成し、被認可側がインポートした後、能動的に認証とその後の同期を完了します。
前提条件¶
- デプロイメントプランのサービスが、少なくとも 2026-06-03 リリースバージョンにアップグレードされている必要があります。この記事で説明する新しいバージョンのサイト間認可方式は、このバージョン以降でのみサポートされます。
- 認可元と被認可側の両方で、
CrossSiteGrantCfgのサイトアイデンティティ設定とクロスサイト証明書の初期化を完了しておく必要があります。 - 認可元は認可パッケージを生成する前に、現在のサービスが他のサイトから
frontApiServerUrlPrefixFormatまたはCrossSiteGrantCfg.baseUrlを使用してアクセス可能であることを確認する必要があります。 - 被認可側は認可パッケージをインポートした後、能動的に認可元のサイトへアクセスして認証と同期を完了します。認可元が被認可側に能動的にアクセスすることはありません。
- 無料プランのワークスペースではこの機能を利用できません。
利用手順¶
1. 認可元による認可メタの生成¶
認可元のワークスペースで クロスサイト認可メタの生成 API を呼び出し、被認可側のワークスペース UUID、認可データタイプ、インデックス、フィルター条件を渡します。
この API は認可元の pending レコードを 1 件作成し、完全なメタを返します。呼び出し元は、完全なメタを被認可側に渡してインポートしてもらう必要があります。この手順では、被認可側のサイトに能動的にアクセスすることはありません。
2. 被認可側による認可メタのインポート¶
被認可側のワークスペースで クロスサイト認可メタのインポート API を呼び出し、認可元が生成した完全なメタを渡します。
インポート時に、バックエンドはターゲットワークスペースの検証、メタ署名の検証、サイト間関係の検証を実行し、認可元のサイトに能動的にアクセスして認証を完了します。認証に成功すると、被認可側のローカルにミラー認可レコードが作成されます。
3. その後の管理¶
認可レコードの作成後、その後の業務管理は引き続きクロススペース認可 API を使用します。
/wksp_share/listで認可レコードを確認します。/wksp_share/<uuid>/modifyで認可範囲を変更します。/wksp_share/deleteで認可を削除または取り消します。
認可元が認可の正本です。被認可側のミラーレコードは、ローカル表示、ワークスペースセレクター、認可検証、DQL クエリに使用され、状態は同期タスクによって段階的に収束します。
デプロイメントプランの設定¶
設定箇所と反映方法¶
このセクションで説明する frontApiServerUrlPrefixFormat、CrossSiteGrantCfg、CrossSiteGrantMirrorSyncSet、AllSiteBaseUrls は、いずれも Studio バックエンドサービスの設定ファイルのトップレベル設定項目であり、Guanceコンソールやワークスペースで設定するものではありません。
Launcher でデプロイされた環境では、次の手順で変更してください。
- Launcher にログインし、右上隅のアプリケーション設定の変更ページを開きます。
- Namespace が
forethought-core、設定名がcoreの設定項目を探し、設定を変更にチェックを入れます。アプリケーションサービス設定項目マニュアルではこの名前はCoreと表記されていますが、Launcher の現在の画面では実際には小文字のcoreと表示されます。 coreの YAML のトップレベルに、このセクションの設定を追加または変更します。frontApiServerUrlPrefixFormatとCrossSiteGrantCfgは同じ階層に配置し、CrossSiteGrantCfgや他の設定項目の内部には入れないでください。- 保存する際は設定変更後に関連サービスを自動再起動にチェックを入れ、変更を確定してください。Studio はプロセスの起動時にこの設定を読み込むため、再起動していないプロセスには新しい値が適用されません。
Launcher での一連の操作と設定の特定方法の詳細は、アプリケーションサービス設定項目マニュアル - Studio バックエンドサービス を参照してください。
インストーラーでの設定マッピングは以下のとおりです。通常、Kubernetes を直接操作する必要はありません。
| 項目 | 値 |
|---|---|
| Kubernetes Namespace | forethought-core |
| Launcher 設定名 | core(アプリケーションサービス設定項目マニュアルでは Core と表記) |
| Kubernetes ConfigMap | core |
| ConfigMap データキー | config.yaml |
| コンテナ内マウントパス | /config/cloudcare-forethought-backend/config/config.yaml |
注意:コンテナ内の
config.yamlは ConfigMap のマウントによるものです。Pod に直接入って変更しても持続可能な設定にはならず、Pod の再作成後には失われます。Launcher でcoreを変更してください。Kubernetes を運用システムで直接管理している環境の場合は、forethought-coreNamespace のcoreConfigMap を更新し、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 の外部からアクセス可能なルートアドレスです。例:
CrossSiteGrantCfg.baseUrl、issuer、jwksUri がカスタマイズによって上書きされていない場合、システムはこのアドレスに基づいてクロスサイト認可のサイトアイデンティティを導出します。
CrossSiteGrantCfg¶
CrossSiteGrantCfg は、クロスサイトプロトコルの機能、サイトアイデンティティ、証明書の読み込みを制御します。
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 |
メタ内の使い捨て認証 code の有効期間(単位:秒) |
issuer |
JWS iss / aud の検証主体。デフォルトの "{}" は baseUrl を使用することを示す |
baseUrl |
自サイトが他サイトからアクセス可能な front API のルートアドレス。デフォルトは frontApiServerUrlPrefixFormat から導出される |
jwksUri |
自サイトの JWKS 公開鍵ディスカバリーアドレス。デフォルトは baseUrl から導出される |
certificateDir |
クロスサイト認可証明書のディレクトリ |
サイト内のクロススペース認可は、上記のクロスサイトアクセススイッチの影響を受けません。
クロスサイト証明書¶
certificateDir のデフォルトは sysconfig/cross_site_certificates です。ディレクトリ構造は以下のとおりです。
証明書ファイルは、JWS 署名と JWKS 公開鍵ディスカバリーに使用されます。
current_kidは現在の active key を指します。private/<kid>.pemは現在のサイトの署名秘密鍵です。public/<kid>.pemは現在のサイトの署名検証用公開鍵です。- active 秘密鍵、過去の公開鍵、
current_kidはバージョン管理に含めてはいけません。
サービスをアップグレードした後、バックグラウンドのアップグレードスクリプトで初回の証明書セットを初期化する必要があります。キーローテーションが必要な場合は、過去の public key を保持し、古い署名が引き続き検証できるようにしてください。
CrossSiteGrantMirrorSyncSet¶
被認可側のミラー認可レコードは、スケジュールタスクによって認可元の最新状態を能動的に同期します。
CrossSiteGrantMirrorSyncSet:
isOpen: true
staleSeconds: 3600
batchSize: 200
lockExpireSeconds: 1800
crontabSet:
minute: "*/10"
この設定はミラー同期のみに影響し、認可元の正本レコードには影響しません。
同一組織のサイト設定¶
同一組織のクロスサイト認可は、AllSiteBaseUrls.<brandKey> を使用した公式サイトの front API アドレスの解決に依存します。相手側サイトは公式サイトの集合内に存在する必要があり、メタ内の baseUrl / jwksUri が公式アドレスと一致している必要があります。
異なる組織または外部のデプロイメントプランのサイトは、AllSiteBaseUrls によるアドレスの導出に依存せず、メタおよびミラーレコード内の baseUrl、issuer、jwksUri と公開鍵アイデンティティを使用して検証を完了する必要があります。
よくある質問¶
現在のサイトアイデンティティ設定が不完全と表示される¶
確認事項:
frontApiServerUrlPrefixFormatが外部からアクセス可能なアドレスとして設定されているかどうか。CrossSiteGrantCfg.baseUrl、issuer、jwksUriが空または形式エラーになっていないかどうか。certificateDir配下にcurrent_kid、private/<kid>.pem、public/<kid>.pemが存在するかどうか。- 実行中のプロセスに証明書ディレクトリと key ファイルの読み取り権限があるかどうか。
認可パッケージのインポートに失敗する¶
確認事項:
- 被認可側のワークスペースがメタ内の
targetWorkspaceUUIDと一致しているかどうか。 - 認可パッケージが期限切れになっていないかどうか。
- 認可元のサイトが被認可側からアクセス可能かどうか。
- 双方が少なくとも 2026-06-03 リリースバージョンにアップグレード済みかどうか。
- 同一組織のサイトで
AllSiteBaseUrlsが正しく設定されているかどうか。 - 異なる組織のクロスサイトスイッチで現在の方向のアクセスが許可されているかどうか。
ミラーレコードがすぐに更新されない¶
ミラーレコードは被認可側によって能動的に同期されます。CrossSiteGrantMirrorSyncSet.isOpen、スケジュールタスクの設定、認可元サイトの接続性、同期タスクのログを確認してください。