IAM 統合アクセス ポリシーのトラブルシューティング

このドキュメントでは、Agent Gateway 下り（外向き）の IAM 統合アクセス ポリシー（UAP）を構成して適用する際に発生する一般的な問題の診断と解決に役立つ情報を提供します。

ポリシーの適用とアクセス失敗

このセクションでは、適用に関する問題について説明します。

ポリシーが適用されない

現象: IAM 拒否ルールまたは制限付き許可ルールがアクセスをブロックするように構成されているにもかかわらず、エージェントが宛先ツール、MCP サーバー、エンドポイントにアクセスできる。

原因: Agent Gateway 認可拡張機能がドライラン モードで実行されているか、ポリシー バインディングのスコープがターゲット リソースと一致していません。ドライラン モードでは、アクセス決定が評価され、監査用にログに記録されますが、リクエストがブロックされることはありません。

解決策:

  1. ドライラン モードを自動適用モードに切り替える: まず、認可拡張機能の構成ファイル（iap-request-authz-extension.yaml）を確認します。iamEnforcementMode が "DRY_RUN" に設定されている場合は、"ENFORCE" に更新するか、DRY_RUN 設定を削除して、gcloud CLI を使用して拡張機能を再インポートします。

    gcloud service-extensions authz-extensions import EXTENSION_NAME \
    --source=EXTENSION_FILE.yaml \
    --location=LOCATION

    次のように置き換えます。

    • EXTENSION_NAME: 認可拡張機能の名前
    • EXTENSION_FILE: YAML 拡張機能構成のファイル名
    • LOCATION: ゲートウェイがデプロイされている Cloud de Confiance リージョン

  2. ゲートウェイ認可ポリシーの委任を確認する: ゲートウェイ認可ポリシー（policyProfile: REQUEST_AUTHZ）が正しい Agent Gateway インスタンス（target.resources）にバインドされていることを確認します。

  3. ポリシー バインディングのスコープを確認する: IAM UAP が、トラフィックが到着するターゲット リソース スコープにバインドされていることを確認します。

  4. ルールの優先度を調べる: 組み合わせポリシーでは、拒否ルールが同じスコープの許可ルールを明示的にオーバーライドします。ただし、レジストリまたはプロジェクト レベルでバインドされている、より広範な許可ルールを持つ UAP が、条件制限なしでアクセスを許可しているかどうかを確認します。

違反措置の適用プロセスに関するポリシーによってエージェントのアクセスがブロックされる

症状: Agent Gateway ポリシーの適用が有効になっている場合、エージェントの下り（外向き）リクエストが HTTP 403 Forbidden エラーまたは PERMISSION_DENIED エラーで失敗します。

原因:

  • エージェントの ID が UAP で指定されていません。

  • エージェントの ID に、宛先リソースに対する iap.resources.egressViaIAP 権限が付与されていません。

  • 正確な宛先ホスト名が Agent Registry に登録されていない

  • リクエスト属性が UAP の Common Expression Language（CEL）条件を満たしていません。

解決策:

  1. ドライラン モードに切り替えて、中断のないデバッグを行う: 障害の診断中に、認可拡張機能を一時的にドライラン モード（iamEnforcementMode: "DRY_RUN"）に切り替えます。これにより、監査ログの検査中にアクティブなエージェント トラフィックがブロックされなくなります。

  2. Cloud Audit Logs のクエリ: Cloud Audit Logs をクエリして、正確な認可チェックと CEL 属性の評価を検査します。

    gcloud

    次の gcloud logging read コマンドを実行します。

    gcloud logging read \
    'protoPayload.serviceName="iap.googleapis.com" AND protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP" AND protoPayload.status.code!=0' \
    --project=PROJECT_ID \
    --limit=20

    PROJECT_ID は、実際のプロジェクト ID に置き換えます。

    コンソール

    1. Cloud de Confiance コンソールで、[ログ エクスプローラ] ページに移動します。
    2. プロジェクトを選択します。
    3. クエリエディタで、次のクエリを入力します。
          protoPayload.serviceName="iap.googleapis.com"
    protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP"
    protoPayload.status.code!=0
    4. [クエリを実行] をクリックします。
    5. ログエントリを開き、protoPayload.authorizationInfo を調べて、評価に失敗したターゲット リソース URI と権限を確認します。

  3. ホスト名が完全に一致していることを確認する: Agent Gateway は、宛先ホスト名と完全に一致するものを照合します。Google API またはサードパーティ サービスは、SDK バージョン、リージョン クライアント構成、mTLS の使用状況に応じて、複数のホスト名のバリエーションで解決される場合があります（例: us-central1-aiplatform.googleapis.com、us-central1-aiplatform.mtls.googleapis.com、aiplatform.googleapis.com）。

    • 登録済みのターゲットに依存する場合は、すべての完全一致ホスト名のバリエーションがエージェント レジストリに登録されていることを確認します。
    • エージェントが未登録のエンドポイントにアクセスする場合は、未登録のエンドポイント ポリシーで、そのホストとパスに iap.resources.egressViaIAP が付与されていることを確認します。

  4. スコープ全体でポリシー バインディングの範囲を確認する: サポートされている 3 つのスコープのいずれかにポリシー バインディングが存在するかどうかを確認します。

    • レジストリ全体: レジストリ内のすべてのエージェント、MCP サーバー、エンドポイントへのアクセス権を付与します。
    • リソースごと: 登録済みの特定の MCP サーバー、エンドポイント、エージェントへのアクセス権を付与します。
    • 未登録のエンドポイント: Agent Registry の外部の宛先へのアクセスを許可します。
    • 注: ターゲット リソースのポリシー バインディングを記述するときに、返された出力に "etag" フィールドが含まれていてもバインディングがない場合、そのターゲットに IAM ポリシーは存在しません。

一般的な UI、gcloud、REST API のエラー メッセージ

このセクションでは、エラー メッセージとその解決方法について説明します。

ポリシーが見つかりません

エラー メッセージ:

  • コンソール UI: 「リクエストされたポリシーが存在しません。選択したリソースにポリシーが存在することを確認してください。
  • API / gcloud: POLICY_NOT_FOUND / HTTP 404 Not Found

原因: 更新リクエストまたはポリシー バインディングで指定された UAP ID がプロジェクトまたはロケーションに存在しないか、削除されています。

解決策: gcloud iam access-policies list --project=<var>PROJECT_ID</var> --location=global を使用して、プロジェクトで使用可能なすべての UAP を一覧表示し、バインドまたは更新する前に、正確なポリシー ID とロケーションを確認します。

ターゲット バインディングの上限を超えました

エラー メッセージ:

  • コンソール UI: 「選択したターゲットは、アクセス ポリシー バインディングの上限に達しています。新しいバインディングを追加する前に、既存のバインディングを削除してください。
  • API / gcloud: TOO_MANY_ACCESS_POLICY_BINDINGS_PER_TARGET

原因: ターゲット リソース（MCP サーバーやレジストリなど）に、ターゲットごとに許可されている上限を超えるポリシー バインディングをアタッチしようとしました。

解決策: 個々のルールごとに個別の UAP とバインディングを作成するのではなく、複数の許可ルールまたは拒否ルールを 1 つの UAP に統合します。gcloud iam policy-bindings delete を使用して、使用されていないバインディングを削除します。

ポリシー バインディングの上限を超えました

エラー メッセージ:

  • コンソール UI: 「選択したポリシーのバインディング数が上限に達しています。新しいバインディングを追加する前に、既存のバインディングを削除してください。
  • API / gcloud: TOO_MANY_ACCESS_POLICY_BINDINGS_TO_POLICY

原因: 1 つの UAP が、プロジェクト内の多数の異なるターゲット リソースに接続されています。

解決策: レジストリ全体のスコープ（AgentRegistry）やプロジェクト スコープなど、より広いスコープでポリシーをバインドし、CEL 属性条件（destination.agent_registry.mcp_server.name など）を使用して、ポリシールール内の個々のツールへのアクセスを管理します。

条件の上限を超えました

エラー メッセージ:

  • コンソール UI: 「このポリシーは属性条件の最大数に達しました。変更を保存するには、いくつかの条件を削除してください。」
  • API / gcloud: TOO_MANY_CONDITIONS / ポリシーのルールの条件上限を超えました。

原因: 単一の許可ルールまたは拒否ルールに、単一のルールでサポートされているよりも多くのきめ細かいアクセス制御（FGAC）属性条件または複雑なサブ式が含まれています。

解決策: CEL 論理演算子（&&、||）を使用して属性チェックを統合するか、包含ルックアップ（in）を設定するか、同じ UAP 内の複数のルールに式を分割します。

ルールの詳細が最新ではありません

エラー メッセージ:

  • コンソール UI: 「ルールの詳細が最新ではありません。このルールは、このページが読み込まれた後に別のユーザーによって変更されました。編集や削除を行う前に、ページを更新して最新の詳細を取得してください。」
  • API / gcloud: etag の不一致による HTTP 412 Precondition Failed / ABORTED。

原因: 取得後に別の管理者または自動プロセスによって UAP が変更されたため、リクエストの etag がアクティブなサーバーの状態と異なります。

解決策: コンソール ページを更新して、アクティブなポリシーの詳細と etag を取得してから、編集内容を保存します。REST API を使用する場合は、まず GET リクエストを実行してアクティブな "etag" 値を取得し、それを PATCH リクエスト ペイロードに含めます。

ポリシーの最後のルールは削除できません

エラー メッセージ:

  • コンソール UI: 「このルールを削除できません。「デフォルト ポリシー」には少なくとも 1 つのルールを含める必要があります。このルールを削除するには、代わりにポリシーを削除してください。」または「これは <ポリシー名> の最後のルールです。これを削除すると、ポリシーも削除され、関連するすべてのバインディングが完全に削除されます。これにより、エージェントのリソースへのアクセスに影響する可能性があります。」

原因: IAM UAP はルールなしで保存できません。

解決策: ポリシー内の唯一のルールを削除する場合は、ポリシー全体を削除します。ポリシー自体を削除する前に、ポリシーを参照するすべてのポリシー バインディングを削除する必要があります。

[詳細] タブに保存されたカスタム CEL 式

エラー メッセージ:

  • コンソール UI: 「カスタム CEL 式を標準の UI 選択に変換できませんでした。式は [詳細] タブに保存されます。

原因: [条件エディタ]（[詳細設定] タブ）に、標準の条件ビルダーの簡略化されたプルダウン セレクタにマッピングできない複雑な CEL 条件または関数を入力しました。

解決策: このメッセージは情報提供を目的とした通知です。カスタム CEL 条件は有効で、保持されます。[条件エディタ] タブで直接編集を続けます。

次のステップ