デプロイメントプランクロスサイト認可使用説明¶

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

使用前提¶

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

使用フロー¶

1. 認可側が認可メタを生成¶

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

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

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

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

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

3. その後の管理¶

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

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

認可側が認可の事実源です。被認可側のミラーレコードは、ローカル表示、ワークスペースセレクター、認可検証、DQL クエリに使用され、そのステータスは同期タスクを通じて徐々に収束します。

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

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

設定項目の説明：

設定項目	説明
`sameOrgAccessEnable`	自サイトがアクセス側の場合、同一組織のクロスサイト認可データへのアクセスを許可するかどうか
`sameOrgBeAccessedEnable`	自サイトが被アクセス側の場合、同一組織のサイトが自サイトの認可データにアクセスすることを許可するかどうか
`externalOrgAccessEnable`	自サイトがアクセス側の場合、異なる組織のクロスサイト認可データへのアクセスを許可するかどうか
`externalOrgBeAccessedEnable`	自サイトが被アクセス側の場合、異なる組織のサイトが自サイトの認可データにアクセスすることを許可するかどうか
`tempAuthCodeTTL`	メタ内のワンタイム認証コードの有効期限（秒単位）
`issuer`	JWS `iss` / `aud` 検証主体。デフォルトでは `"{}"` は `baseUrl` を使用することを意味します
`baseUrl`	自サイトが他のサイトからアクセス可能な front API のルートアドレス。デフォルトでは `frontApiServerUrlPrefixFormat` から派生します
`jwksUri`	自サイトの JWKS 公開鍵検出アドレス。デフォルトでは `baseUrl` から派生します
`certificateDir`	クロスサイト認可証明書ディレクトリ

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

クロスサイト証明書¶

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¶

被認可側のミラー認可レコードは、スケジュールタスクを通じて能動的に認可側の最新ステータスを同期します。

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

この設定はミラー同期にのみ影響し、認可側の事実レコードには影響しません。

同一組織サイト設定¶

同一組織のクロスサイト認可は、AllSiteBaseUrls.<brandKey> に依存して公式サイトの front API アドレスを解決します。相手側サイトは公式サイトコレクションに存在する必要があり、メタ内の baseUrl / jwksUri は公式アドレスと一致している必要があります。

異なる組織のサイトや外部デプロイメントプランサイトは、AllSiteBaseUrls に依存してアドレスを導出するべきではありません。代わりに、メタとミラーレコード内の baseUrl、issuer、jwksUri、および公開鍵 ID を使用して検証を完了する必要があります。

よくある質問¶

現在のサイト ID 設定が不完全であると表示される¶

以下を確認してください。

frontApiServerUrlPrefixFormat が外部からアクセス可能なアドレスとして設定されているか。
CrossSiteGrantCfg.baseUrl、issuer、jwksUri が空または形式が間違っていないか。
certificateDir の下に current_kid、private/<kid>.pem、public/<kid>.pem が存在するか。
実行中のプロセスに、証明書ディレクトリとキーファイルを読み取る権限があるか。

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