Service Extensions を使用して認可を委任する

このページでは、Service Extensions を使用して、Agent Gateway の認可を Identity-Aware Proxy、Model Armor、その他のカスタム認可エンジンに委任する方法について説明します。

認可ポリシーと拡張機能

認可ポリシーを使用すると、Agent Gateway によって公開されたエンドポイントを通過するトラフィックに、一元化されたアクセス制御ポリシーとガバナンス ポリシーを適用できます。複雑なアクセス制御、コンテンツの安全性、ガバナンスの決定を処理するために、Agent Gateway では、認可拡張機能を使用して認可ポリシーを構成できます。これにより、認可とコンテンツの安全性に関する決定を、選択した指定の認可エンジンに委任できます。

認可拡張機能は、Agent Gateway デプロイを通過するリクエストをインターセプトし、指定された認可サービスにリアルタイムの gRPC 呼び出しを行います。これにより、サービスはトラフィックを検査、変更、またはブロックしてから、宛先に送信できます。Identity-Aware Proxy、Model Armor、セマンティック ガバナンス ポリシーなどの Google Cloud サービス、または任意のカスタム認可エンジンに認可を委任できます。

認可ポリシーは、ポリシー プロファイルを使用して、認可拡張機能に送信されるトラフィック データのタイプを決定します。

  • リクエストベースの認可(REQUEST_AUTHZ): アプリケーション ペイロードが処理される前に HTTP リクエスト ヘッダーを評価します。このプロファイルは、本人確認とアクセス制御(Identity-Aware Proxy への認可の委任など)に使用されます。
  • コンテンツ ベースの認可(CONTENT_AUTHZ): 完全な HTTP リクエストとレスポンスのペイロードを評価します。このプロファイルは、プロンプトとレスポンスの安全性に関する Model Armor への委任や、自然言語制約の適用に関するセマンティック ガバナンス ポリシーへの委任など、詳細なコンテンツ検査と AI の安全性に使用されます。

カスタム認可エンジンは、ヘッダーまたはアプリケーション ペイロード全体を検査するかどうかに応じて、REQUEST_AUTHZ 拡張機能または CONTENT_AUTHZ 拡張機能を使用できます。

認可拡張機能は、リクエストベースのポリシーとコンテンツベースのポリシーで個別に構成することも、ゲートウェイで両方を組み合わせて包括的なセキュリティを実現することもできます。推奨構成については、推奨される上り(内向き)と下り(外向き)の構成をご覧ください。

認可ポリシー、ポリシー プロファイル、それらのユースケースの詳細については、認可ポリシーの概要をご覧ください。

エージェントのライフサイクル全体にわたって包括的なセキュリティを確保するには、次のマルチゲートウェイ アーキテクチャ パターンをおすすめします。

  • クライアントからエージェントへのゲートウェイ: クライアントからエージェントへの(上り(内向き))ゲートウェイは、1 つの CONTENT_AUTHZ ポリシーのみをサポートします。つまり、上り(内向き)で Model Armor とセマンティック ガバナンス ポリシーを併用することはできません。プロンプト インジェクション攻撃から保護するために、Model Armor の CONTENT_AUTHZ ポリシーを使用することを強くおすすめします。ただし、代わりにセマンティック ガバナンス ポリシー拡張機能を使用する場合は、ゲートウェイで Model Armor が構成されていないことを確認する必要があります。他のタイプのサービス拡張機能は、Ingress ゲートウェイではサポートされていません。

  • エージェントから任意の場所へのゲートウェイ: エージェントから任意の場所への(下り(外向き))ゲートウェイは、最大 4 つの認可ポリシーをサポートします。下り(外向き)ゲートウェイは、REQUEST_AUTHZ と CONTENT_AUTHZ の両方のポリシー プロファイルをサポートしています。この上限内で、各タイプの複数のポリシーを構成できます。

    次の構成をおすすめします。

    • エージェント ID を認可するために Identity-Aware Proxy(IAP)に委任する REQUEST_AUTHZ ポリシー。
    • 1 つ以上の CONTENT_AUTHZ ポリシー。Model Armor またはセマンティック ガバナンス ポリシーにさらに決定を委任して、機密データの漏洩を防ぎ、送信されるツール呼び出しとレスポンスに自然言語の制約を適用します。

    ポリシーの評価方法の詳細については、下り(外向き)のポリシー評価をご覧ください。

このマルチゲートウェイ トポロジにより、Model Armor が受信プロンプトをスクリーニングし、IAP、Model Armor、セマンティック ガバナンス ポリシーが送信レスポンスをスクリーニングします。

下り(外向き)のポリシー評価

下り(外向き)ゲートウェイに複数の認可ポリシーが構成されている場合、ポリシー プロファイル タイプに応じて、次の順序で評価されます。

  1. REQUEST_AUTHZ(ヘッダーベース)ポリシー: これらのポリシータイプは最初に評価されます。たとえば、IAP 拡張機能は、コンテンツが処理される前に、呼び出し元エージェントの mTLS ID を確認し、IAM 許可ポリシーを検証します。リクエストがこのチェックに失敗すると、すぐに拒否されます。
  2. CONTENT_AUTHZ(コンテンツ ベース)ポリシー: 次に評価されるポリシータイプです。リクエストがヘッダーベースのチェックに合格すると、ペイロードはコンテンツベースの認可拡張機能(セマンティック ガバナンス Policy Engine など)にストリーミングされ、詳細なコンテンツ検査とコンプライアンス評価が行われます。

始める前に

開始する前に、次の要件を満たしていることを確認してください。

  • Agent Gateway がデプロイされます。Agent Gateway を構成するをご覧ください。

  • ゲートウェイに認可ポリシーを接続するには、デプロイされた Agent Gateway リソースに対する networkservices.agentGateways.use IAM 権限が必要です。

拡張機能を使用して認可ポリシーを構成する

このセクションでは、認可とコンテンツの安全性の判断を Identity-Aware Proxy、Model Armor、その他のカスタム サービスに委任する認可ポリシーを構成する方法について説明します。

IAP に認可を委任する

リクエスト認可拡張機能を構成して、認可ポリシーのアクセス決定を IAP に委任できます。

次の手順では、Agent Gateway インスタンスの認可ポリシーを使用して認可拡張機能を構成する方法について説明します。

  1. 始める前に: リソースへのアクセス ポリシーのバインドを無効にする(constraints/iam.managed.disableAccessPolicyBindings)マネージド組織ポリシーの制約の適用を無効にします。デフォルトでは、このブール型制約は新しい組織で有効になっており、IAM 統合アクセス ポリシーをリソースにバインドできなくなります。詳細については、ブールルールを使用したポリシーの更新をご覧ください。

  2. エージェントとツールに必要な IAM 下り(外向き)ポリシーを作成します。詳細については、IAM エージェント ポリシーを作成するをご覧ください。

  3. Agent Gateway の作成時に IAP を有効にするには(アクセス認可パラメータを使用)、Agent-to-Anywhere(下り(外向き))モードで Agent Gateway を構成するをご覧ください。

  4. IAP を参照するように認可拡張機能を構成します。

    1. YAML ファイルで拡張機能を定義します。提供されているサンプル値を使用します。ドライランの監査専用モードで拡張機能をデプロイし、認可ポリシーを適用せずにテストする場合は、metadata ブロック内に iamEnforcementMode フィールドを指定します。

      cat >iap-request-authz-extension.yaml <<EOF
      name: my-iap-request-authz-ext
      service: iap.googleapis.com
      failOpen: false
      timeout: 1s
      metadata:
        iapPolicyVersion: "V2"
      EOF
      

      ドライランの監査専用モードで拡張機能をデプロイし、認可ポリシーを適用せずにテストする場合は、metadata ブロック内に iamEnforcementMode フィールドを指定します。これにより、ポリシーを検証し、構成エラーによるトラフィックの中断のリスクを最小限に抑えることができます。

      cat >iap-request-authz-extension.yaml <<EOF
      name: my-iap-request-authz-ext
      service: iap.googleapis.com
      failOpen: false
      timeout: 1s
      metadata:
        iapPolicyVersion: "V2"
        iamEnforcementMode: "DRY_RUN"
      EOF
      

      ポリシーの適用を開始する準備ができたら、metadata ブロックから iamEnforcementMode: "DRY_RUN" フィールドを削除します(または、 Google Cloud コンソールで [ポリシーを適用する] を選択します)。適用を有効にする前にドライラン違反を監査する手順については、コントロール全体でドライラン ポリシー違反を監査するをご覧ください。

    2. 認可拡張機能をインポートします。次のサンプル値を使用して gcloud service-extensions authz-extensions import コマンドを使用します。

      gcloud service-extensions authz-extensions import my-iap-request-authz-ext \
          --source=iap-request-authz-extension.yaml \
          --location=LOCATION
      
  5. 同じプロジェクトで、決定を拡張機能に委任する認可ポリシーを構成します。

    1. my-iap-request-authz-ext 拡張機能をゲートウェイに関連付ける認可ポリシーを定義します。提供されているサンプル値を使用します。

      cat >iap-request-authz-policy.yaml <<EOF
      name: my-iap-request-authz-policy
      target:
        resources:
          - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
      policyProfile: REQUEST_AUTHZ
      action: CUSTOM
      customProvider:
        authzExtension:
          resources:
            - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/my-iap-request-authz-ext"
      EOF
      

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

    2. 認可ポリシーをプロジェクトにインポートします。次のサンプル値を使用して gcloud network-security authz-policies import コマンドを使用します。

      gcloud network-security authz-policies import my-iap-request-authz-policy \
          --source=iap-request-authz-policy.yaml \
          --location=LOCATION
      

Model Armor に認可を委任する

認可拡張機能を構成して、認可ポリシーのコンテンツ セキュリティの決定を Model Armor に委任できます。Model Armor テンプレートは、Agent Gateway やエージェントと同じプロジェクトに配置することも、中央のセキュリティ プロジェクトやガバナンス プロジェクトなどの別のプロジェクトに配置することもできます。

次の例は、Agent Gateway の認可ポリシーを使用してこのような認可拡張機能を構成する方法を示しています。

コンソール

Google Cloud コンソールを使用して Agent Gateway で Model Armor を有効にするには、次の操作を行います。

  1. 必要な Model Armor テンプレートを作成します。

  2. Agent Gateway の作成時に Model Armor を有効にするには([Model Armor を有効にする] チェックボックスを使用)、Agent Gateway を構成するをご覧ください。Model Armor テンプレートは、Client-to-Agent モードと Agent-to-Anywhere モードの両方でサポートされています。

  3. Model Armor を使用する場合は、Model Armor テンプレートを使用するために必要な権限を Agent Gateway サービス アカウントに付与する必要があります。サービス アカウントの形式は service-PROJECT_NUMBER@gcp-sa-dep. です。ここで、PROJECT_NUMBER はゲートウェイを作成したプロジェクトのプロジェクト番号です。

    ゲートウェイとテンプレートの両方が同じプロジェクトにある場合でも、この手順を完了する必要があります。次のロールを付与します。

    • ゲートウェイを含むプロジェクトの roles/modelarmor.calloutUser ロールと roles/serviceusage.serviceUsageConsumer ロール。
    • Model Armor テンプレートを含むプロジェクトの roles/modelarmor.user ロール。

    この手順を完了するには、gcloud CLI を使用する必要があります。

    gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
        --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \
        --role=roles/modelarmor.calloutUser
    gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
        --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \
        --role=roles/serviceusage.serviceUsageConsumer
    gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
        --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \
        --role=roles/modelarmor.user
    

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

    • GATEWAY_PROJECT_ID: ゲートウェイを作成したプロジェクトのプロジェクト ID。
    • GATEWAY_PROJECT_NUMBER: ゲートウェイを作成したプロジェクトのプロジェクト番号。
    • MODEL_ARMOR_PROJECT_ID: Model Armor テンプレートを含むプロジェクトのプロジェクト ID。

    Agent Runtime にゲートウェイを使用している場合、Agent Gateway を介して Agent Runtime トラフィックをルーティングするに記載されているように、Agent Runtime サービス エージェントにもこれらの権限が必要です。

gcloud

  1. 必要な Model Armor テンプレートを作成します。

  2. Model Armor を使用する場合は、Model Armor テンプレートを使用するために必要な権限を Agent Gateway サービス アカウントに付与する必要があります。サービス アカウントの形式は service-PROJECT_NUMBER@gcp-sa-dep. です。ここで、PROJECT_NUMBER はゲートウェイを作成したプロジェクトのプロジェクト番号です。

    ゲートウェイとテンプレートの両方が同じプロジェクトにある場合でも、この手順を完了する必要があります。次のロールを付与します。

    • ゲートウェイを含むプロジェクトの roles/modelarmor.calloutUser ロールと roles/serviceusage.serviceUsageConsumer ロール。
    • Model Armor テンプレートを含むプロジェクトの roles/modelarmor.user ロール。
    gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
        --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \
        --role=roles/modelarmor.calloutUser
    gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
        --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \
        --role=roles/serviceusage.serviceUsageConsumer
    gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
        --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \
        --role=roles/modelarmor.user
    

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

    • GATEWAY_PROJECT_ID: ゲートウェイを作成したプロジェクトのプロジェクト ID。
    • GATEWAY_PROJECT_NUMBER: ゲートウェイを作成したプロジェクトのプロジェクト番号。
    • MODEL_ARMOR_PROJECT_ID: Model Armor テンプレートを含むプロジェクトのプロジェクト ID。
  3. Model Armor を参照するように認可拡張機能を構成します。

    1. YAML ファイルで拡張機能を定義します。提供されているサンプル値を使用します。

      cat >ma-content-authz-extension.yaml <<EOF
      name: my-ma-content-authz-ext
      service: modelarmor.LOCATION.rep.googleapis.com
      metadata:
        model_armor_settings: '[
          {
          "response_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
          "request_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID"
          }
        ]'
      failOpen: false
      timeout: 1s
      EOF
      
    2. 認可拡張機能をインポートします。次のサンプル値を使用して gcloud service-extensions authz-extensions import コマンドを使用します。

      gcloud service-extensions authz-extensions import my-ma-content-authz-ext \
         --source=ma-content-authz-extension.yaml \
         --location=LOCATION
      
  4. 拡張機能を使用して認可ポリシーを構成します。

    1. 拡張機能 my-ma-content-authz-ext を Agent Gateway に関連付ける認可ポリシーを定義します。

      エージェントから任意の宛先へ

      cat >ma-content-authz-policy.yaml <<EOF
      name: my-ma-content-authz-policy
      target:
        resources:
          - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
      policyProfile: CONTENT_AUTHZ
      action: CUSTOM
      customProvider:
        authzExtension:
          resources:
            - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/my-ma-content-authz-ext"
      httpRules:
        - to:
            operations: [ { "paths": [ { "prefix": "/" } ] } ]
          when: >
            request.headers['content-type'] == 'application/json' ||
            request.headers['content-type'].startsWith('text/')
      EOF
      

      次の点にご注意ください。

      • policyProfile の値は CONTENT_AUTHZ に設定されています。これは、カスタム ポリシー プロバイダがリクエスト本文を含むリクエスト トラフィックとレスポンス トラフィックを処理することを示します。

      • httpRules パラメータは、CEL 属性を使用して、評価のために Model Armor に転送する特定のトラフィックに一致する条件を作成する方法を示しています。この例では、ルールは application/json または text/ のコンテンツ タイプを持つすべてのトラフィックと一致します。このようなルールを使用して、Model Armor の評価を関連するトラフィックに制限することをおすすめします。これにより、サポートされている LLM API、MCP、A2A トラフィックを Model Armor にルーティングし、エージェントの gRPC 呼び出しなどの内部トラフィックを除外できます。

      クライアントからエージェントへ

      cat >ma-content-authz-policy.yaml <<EOF
      name: my-ma-content-authz-policy
      target:
        resources:
          - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
      policyProfile: CONTENT_AUTHZ
      action: CUSTOM
      customProvider:
        authzExtension:
          resources:
            - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/my-ma-content-authz-ext"
      EOF
      

      policyProfile の値は CONTENT_AUTHZ に設定されています。これは、カスタム ポリシー プロバイダがリクエスト本文を含むリクエスト トラフィックとレスポンス トラフィックを処理することを示します。

    2. 認可ポリシーをプロジェクトにインポートします。次のサンプル値を使用して gcloud network-security authz-policies import コマンドを使用します。

      gcloud network-security authz-policies import my-ma-content-authz-policy \
        --source=ma-content-authz-policy.yaml \
        --location=LOCATION
      

Terraform

google プロバイダを使用して Model Armor 認可拡張機能と CONTENT_AUTHZ ポリシーを宣言的に構成するには、必要なサービス エージェントの IAM バインディング、認可拡張機能、認可ポリシーを定義します。この構成は、Model Armor テンプレートが Agent Gateway およびエージェントと同じプロジェクトにあるか、別のプロジェクトにあるかに関係なく適用されます。Model Armor テンプレートが、エージェントまたは Agent Gateway を含むプロジェクトとは異なるプロジェクトにあり、VPC Service Controls を使用している場合、両方のプロジェクトが同じ VPC Service Controls サービス境界内にある必要があります。

  1. Agent Gateway を含むプロジェクトと、Model Armor テンプレートを含むプロジェクトで、Service Extensions サービス エージェントに必要なロールを付与します。ゲートウェイとテンプレートの両方が同じプロジェクトにある場合でも、この手順を完了する必要があります。

    resource "google_project_iam_member" "dep_ma_callout_user" {
      project = "PROJECT_ID"
      role    = "roles/modelarmor.calloutUser"
      member  = "serviceAccount:service-PROJECT_NUMBER@gcp-sa-dep."
    }
    
    resource "google_project_iam_member" "dep_service_usage_consumer" {
      project = "PROJECT_ID"
      role    = "roles/serviceusage.serviceUsageConsumer"
      member  = "serviceAccount:service-PROJECT_NUMBER@gcp-sa-dep."
    }
    
    resource "google_project_iam_member" "dep_ma_template_user" {
      project = "MODEL_ARMOR_PROJECT_ID"
      role    = "roles/modelarmor.user"
      member  = "serviceAccount:service-PROJECT_NUMBER@gcp-sa-dep."
    }
    

    Agent Runtime にゲートウェイを使用している場合、Agent Runtime サービス エージェントには、Agent Gateway を介して Agent Runtime トラフィックをルーティングするに記載されている権限も必要です。

  2. Model Armor を指す google_network_services_authz_extension リソースを定義します。

    resource "google_network_services_authz_extension" "ma_content_authz_ext" {
      project   = "PROJECT_ID"
      location  = "LOCATION"
      name      = "my-ma-content-authz-ext"
      service   = "modelarmor.LOCATION.rep.googleapis.com"
      timeout   = "1s"
      fail_open = false
    
      metadata = {
        model_armor_settings = jsonencode([
          {
            response_template_id = "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID"
            request_template_id  = "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID"
          }
        ])
      }
    
      depends_on = [
        google_project_iam_member.dep_ma_callout_user,
        google_project_iam_member.dep_service_usage_consumer,
        google_project_iam_member.dep_ma_template_user,
      ]
    }
    
  3. google_network_security_authz_policy リソースを使用して、拡張機能を Agent Gateway に接続します。

    エージェントから任意の宛先へ

    resource "google_network_security_authz_policy" "ma_content_authz_policy" {
      project        = "PROJECT_ID"
      location       = "LOCATION"
      name           = "my-ma-content-authz-policy"
      policy_profile = "CONTENT_AUTHZ"
      action         = "CUSTOM"
    
      target {
        resources = [
          "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
        ]
      }
    
      custom_provider {
        authz_extension {
          resources = [
            google_network_services_authz_extension.ma_content_authz_ext.id
          ]
        }
      }
    
      http_rules {
        to {
          operations {
            paths {
              prefix = "/"
            }
          }
        }
        when = "request.headers['content-type'] == 'application/json' || request.headers['content-type'].startsWith('text/')"
      }
    }
    

    クライアントからエージェントへ

    resource "google_network_security_authz_policy" "ma_content_authz_policy" {
      project        = "PROJECT_ID"
      location       = "LOCATION"
      name           = "my-ma-content-authz-policy"
      policy_profile = "CONTENT_AUTHZ"
      action         = "CUSTOM"
    
      target {
        resources = [
          "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
        ]
      }
    
      custom_provider {
        authz_extension {
          resources = [
            google_network_services_authz_extension.ma_content_authz_ext.id
          ]
        }
      }
    }
    

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

  • PROJECT_ID: Agent Gateway を作成したプロジェクトのプロジェクト ID。

  • PROJECT_NUMBER: Agent Gateway を作成したプロジェクトのプロジェクト番号。

  • MODEL_ARMOR_PROJECT_ID: Model Armor テンプレートを含むプロジェクトのプロジェクト ID。これは、PROJECT_ID と同じプロジェクトにすることも、別のプロジェクトにすることもできます。テンプレートがエージェントまたは Agent Gateway プロジェクトとは異なるプロジェクトにあり、VPC Service Controls を使用している場合、両方のプロジェクトが同じサービス境界内にある必要があります。

  • LOCATION: Agent Gateway と Model Armor テンプレートが配置されているリージョン。

  • TEMPLATE_ID: Model Armor テンプレートの ID。

  • AGENT_GATEWAY_NAME: Agent Gateway リソースの名前。

カスタム認可拡張機能に認可を委任する

カスタム認可拡張機能を構成して、カスタム サービスに判断を委任できます。これらのカスタム拡張機能は、完全修飾ドメイン名(FQDN)のみをターゲットにできます。

FQDN ターゲットを使用する場合、拡張機能は TLS 暗号化を使用した HTTP2 プロトコルを使用して、ポート 443 のエンドポイントと通信します。ただし、この拡張機能はサーバー証明書を検証しません。したがって、セキュリティを強化するには、解決されたエンドポイントが VPC ネットワーク内にあることを確認する必要があります。また、Agent Gateway プロジェクトと VPC ネットワークの間に DNS ピアリングが設定されていることを確認します。

  1. 特定の FQDN(mycustomauthz.internal.net など)の認可ポリシーを使用して認可拡張機能を構成するには、次の例に示すように、拡張機能の YAML ファイルで service の値として指定します。この例では、FULL_DUPLEX_STREAMED 本文処理モードで ext_proc プロトコルを実装するサーバーを VPC ネットワークにデプロイしていることを前提としています。

    cat >custom-authz-extension.yaml <<EOF
    name: my-custom-authz-ext
    service: mycustomauthz.internal.net
    failOpen: false
    timeout: 1s
    EOF
    
  2. カスタム サービスを指す認可拡張機能を作成します。

    gcloud beta service-extensions authz-extensions import custom-authz-extension \
      --source=custom-authz-extension.yaml \
      --location=LOCATION
    
  3. 拡張機能を作成したら、認可の決定を認可拡張機能に委任する CUSTOM 認可ポリシーを構成します。

      cat >authz-policy.yaml <<EOF
      name: authz-with-extension
      target:
        resources:
          - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
      policyProfile: CONTENT_AUTHZ
      action: CUSTOM
      customProvider:
        authzExtension:
          resources:
            - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/custom-authz-extension"
      EOF
    
  4. 認可ポリシーを作成します。

    gcloud network-security authz-policies import authz-policy-with-extension \
    --source=authz-policy.yaml \
    --location=LOCATION
    

この例に示すように、CONTENT_AUTHZ プロファイルを使用して認可拡張機能が認可ポリシーに関連付けられている場合、ゲートウェイはリクエストとレスポンスのペイロード(ヘッダーと本文)に対して拡張機能を呼び出します。これにより、エージェント トラフィックのディープ コンテンツ検査、プロンプト ガードレール、データ サニタイズが可能になります。デフォルトでは、CONTENT_AUTHZ ポリシーは FULL_DUPLEX_STREAMED モードの Envoy ext_proc プロトコルを使用して本文イベントを処理します。

IAP 認可と Model Armor ガードレールを組み合わせる

包括的なセキュリティを確保するには、REQUEST_AUTHZ ポリシー プロファイルを使用して CUSTOM 認可ポリシーを設定し、CONTENT_AUTHZ ポリシー プロファイルを使用して別の CUSTOM 認可ポリシーを設定することをおすすめします。

次の例では、一元化されたリクエスト認可システムとして IAP を使用し、AI ガードレールとして Model Armor を使用しています。前の例で示したように、これらをサービス拡張機能に置き換えて、独自のカスタム ソリューションを使用できます。

  1. IAP に委任する REQUEST_AUTHZ 認可拡張機能と、その拡張機能を指す認可ポリシーを構成します。

    1. 認可拡張機能を定義します。metadata の iapPolicyVersion フィールドは必須です。

      cat >iap-extension.yaml <<EOF
      name: iap-extension
      service: iap.googleapis.com
      failOpen: false
      timeout: 1s
      metadata:
        iapPolicyVersion: "V2"
      EOF
      
    2. 認可拡張機能を作成します。

      gcloud service-extensions authz-extensions import iap-extension \
      --source=iap-extension.yaml \
      --location=LOCATION
      

      LOCATION は、拡張機能のリージョンに置き換えます。

    3. 拡張機能に委任する REQUEST_AUTHZ 認可ポリシーを構成します。

      cat >authz-policy-request-authz.yaml <<EOF
      name: authz-iap
      target:
        resources:
        - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
      policyProfile: REQUEST_AUTHZ
      action: CUSTOM
      customProvider:
        authzExtension:
          resources:
          - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/iap-extension"
      EOF
      

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

      • PROJECT_ID: プロジェクト ID。
      • LOCATION: リソースのロケーション。
      • AGENT_GATEWAY_NAME: Agent Gateway の名前。
    4. 認可ポリシーを作成します。

      gcloud network-security authz-policies import authz-iap \
      --source=authz-policy-request-authz.yaml \
      --location=LOCATION
      
  2. Model Armor に委任する CONTENT_AUTHZ 認可拡張機能と、その拡張機能を指す認可ポリシーを構成します。

    1. 拡張機能を定義します。

      cat >ma-extension-file.yaml <<EOF
      name: ma-extension
      service: modelarmor.LOCATION.rep.googleapis.com
      metadata:
        model_armor_settings: '[
          {
          "response_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE_ID",
          "request_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/REQUEST_TEMPLATE_ID"
          }
        ]'
      failOpen: false
      timeout: 1s
      EOF
      

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

      • LOCATION: Model Armor テンプレートが配置されているリージョン。
      • MODEL_ARMOR_PROJECT_ID: Model Armor テンプレートを含むプロジェクト ID。
      • RESPONSE_TEMPLATE_ID: 返信定型文の ID。
      • REQUEST_TEMPLATE_ID: リクエスト テンプレートの ID。
    2. 認可拡張機能を作成します。

      gcloud service-extensions authz-extensions import ma-extension \
      --source=ma-extension-file.yaml \
      --location=LOCATION
      
    3. 拡張機能に委任する CONTENT_AUTHZ 認可ポリシーを構成します。

      cat >authz-policy-content-authz.yaml <<EOF
      name: authz-ma
      target:
        resources:
        - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
      policyProfile: CONTENT_AUTHZ
      action: CUSTOM
      customProvider:
        authzExtension:
          resources:
          - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/ma-extension"
      EOF
      
    4. 認可ポリシーを作成します。

      gcloud network-security authz-policies import ma-authz-policy \
      --source=authz-policy-content-authz.yaml \
      --location=LOCATION
      

認可拡張機能が CONTENT_AUTHZ プロファイルに関連付けられている場合、リクエスト ヘッダーとレスポンス ヘッダー、本文、トレーラーを含むすべての ext_proc イベントを受信します。ext_proc ベースの認可拡張機能がリクエスト時の認可とコンテンツ ベースの認可の両方を処理できる場合は、CONTENT_AUTHZ ポリシー プロファイルを使用して単一の CUSTOM 認可ポリシーを構成することをおすすめします。このポリシーは、多用途の認可拡張機能を指す必要があります。このアプローチでは、単一の拡張機能と ext_proc 接続を介して両方のタイプの認可が可能になり、レイテンシ プロファイルを改善できます。

セマンティック ガバナンス ポリシーに認可を委任する

認可拡張機能を構成して、認可ポリシーのインテント ゲーティングと自然言語制約の決定をセマンティック ガバナンス ポリシー エンジン(semanticGovernancePolicyEngine)に委任できます。

ポリシー エンジンをプロビジョニングし、ゲートウェイに必要な CONTENT_AUTHZ 認可ポリシーと認可拡張機能バインディングを作成する方法については、ポリシー エンジンを Agent Gateway に接続するをご覧ください。

MCP プロトコル属性に基づく認可

Agent Gateway は、リクエスト内の MCP プロトコル ペイロードを解析し、抽出された属性を認可ポリシーで使用できるようにします。

特定のツールの名前など、MCP メソッド パラメータに基づいてアクセスを制限できます。このセクションでは、ALLOW ポリシーと DENY の 2 つの例を示します。

  1. 認可ポリシーを構成します。

    ALLOW ポリシーの例

    この例では、MCP サーバー上の特定のツールセットと基本プロトコル機能へのアクセスを許可しますが、プロンプトとリソースへのアクセスは許可しません。

    ALLOW ポリシーを作成するときは、初期化、ロギング、完了、通知、ping などのアクセス固有でない MCP RPC が引き続き機能するように、baseProtocolMethodsOption: MATCH_BASE_PROTOCOL_METHODS を指定してください。そうしないと、MCP セッションを確立できません。

    cat >authz-policy-restrict-tools.yaml <<EOF
    name: my-authz-policy-restrict-tools
    target:
      resources:
      - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
    policyProfile: REQUEST_AUTHZ
    httpRules:
    - to:
        operations:
        - mcp:
            baseProtocolMethodsOption: MATCH_BASE_PROTOCOL_METHODS
            methods:
            - name: "tools/list"
            - name: "tools/call"
              params:
              - exact: "get_weather"
              - exact: "get_location"
    action: ALLOW
    EOF
    

    DENY ポリシーの例

    この例では、Agent Gateway の背後にある MCP サーバーへのすべての prompts/ メソッド アクセスを禁止しています。

    cat >authz-policy-disallow-prompts.yaml <<EOF
    name: my-authz-policy-disallow-prompts
    target:
      resources:
      - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
    policyProfile: REQUEST_AUTHZ
    httpRules:
    - to:
        operations:
        - mcp:
            methods:
            - name: "prompts"
    action: DENY
    EOF
    
  2. 認可ポリシーを作成します。

    gcloud network-security authz-policies import AUTHZ_POLICY_NAME \
    --source=AUTH_POLICY_YAML_FILE_PATH \
    --location=LOCATION
    

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

    • AUTHZ_POLICY_NAME: 認可ポリシーの名前。
    • AUTH_POLICY_YAML_FILE_PATH: 認可ポリシーの YAML ファイルのパス。
    • LOCATION: リソースのロケーション。

制限事項

認可ポリシーを使用する場合は、次の制限事項が適用されます。

  • ゲートウェイあたりの認可ポリシーの最大数は、ゲートウェイ モードによって異なります。

    • Agent-to-Anywhere(下り(外向き))ゲートウェイの場合、ポリシー プロファイル(REQUEST_AUTHZ または CONTENT_AUTHZ)に関係なく、ゲートウェイごとに最大 4 つの認可ポリシーを構成できます。
    • クライアントからエージェント(上り(内向き))ゲートウェイの場合、最大 1 つの CONTENT_AUTHZ ポリシーを構成できます。

    詳細については、推奨される上り(内向き)と下り(外向き)の構成をご覧ください。

  • CONTENT_AUTHZ プロファイルでカスタム認可拡張機能を使用する場合は、本文イベントの ext_proc プロトコルと FULL_DUPLEX_STREAMED モードをサポートする必要があります。

  • 同じプロファイルを使用する複数のカスタム認可ポリシーを構成する場合、実行順序は保証されません。

また、認可拡張機能の制限事項の詳細については、次のセクションをご覧ください。

次のステップ

Codelab

Gemini Enterprise Agent Platform の Agent Gateway でエージェント ワークロードを管理する方法について説明します。

ガイド

Agent Gateway リソースを表示、更新、関連付け解除、削除する方法について説明します。

ガイド

Agent Gateway をモニタリングする方法について説明します。

トラブルシューティング

Agent Gateway の接続に関するトラブルシューティング方法について説明します。