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

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

認可ポリシーを使用すると、Agent Gateway によって公開されたエンドポイントを通過するトラフィックに、一元化されたアクセス制御ポリシーとガバナンス ポリシーを適用できます。これらのポリシーを使用すると、mTLS ID、リクエストとレスポンスの属性に基づいてアクセスを制御することでトラフィックを管理できます。また、使用されるプロトコル固有の属性（MCP サーバーなど）に基づいてカスタマイズすることもできます。

認可ポリシーは、ポリシー プロファイルを使用して、実行する認可のタイプを決定します。HTTP リクエスト ヘッダーの情報に基づいてトラフィックを許可または拒否するリクエストベースの認可ポリシー（REQUEST_AUTHZ）を使用できます。または、トラフィックを許可または拒否するためにアプリケーション ペイロードの詳細な検査を行う必要がある場合は、コンテンツ ベースの認証ポリシー（CONTENT_AUTHZ）を使用できます。

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

認可拡張機能

複雑な認可の決定は、認可ポリシーを使用して簡単に表現できない場合があります。Agent Gateway を使用すると、認可拡張機能で認可ポリシーを構成して、認可の決定をカスタム認可エンジンに委任できます。

認可拡張機能を使用すると、Agent Gateway デプロイを通過するリクエストをインターセプトして評価できます。管理している外部サービスにリアルタイムの gRPC 呼び出しを行い、トラフィックが宛先に到達する前に、トラフィックの検査、変更、ブロックを行うことができます。

拡張機能は、構成された認可ポリシーに基づいてデータを検査します。リクエスト ベースとコンテンツ ベースの認可ポリシーに対して認可拡張機能を個別に構成することも、包括的なセキュリティのために両方を使用することもできます。

始める前に

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

  • エージェント ゲートウェイがデプロイされます。エージェント ゲートウェイを構成するをご覧ください。

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

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

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

IAP に認可を委任する

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

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

コンソール

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

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

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

    IAP では、エージェントがゲートウェイにバインドされたエージェント レジストリ リソースに登録されている必要があります。

gcloud

  1. IAP を指すように認可拡張機能を構成します。

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

      cat >iap-request-authz-extension.yaml <<EOF
name: my-iap-request-authz-ext
service: iap.googleapis.com
failOpen: true
EOF

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

      cat >iap-request-authz-extension.yaml <<EOF
name: my-iap-request-authz-ext
service: iap.googleapis.com
failOpen: true
metadata: '
  iamEnforcementMode: DRY_RUN
'
EOF

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

      gcloud beta service-extensions authz-extensions import my-iap-request-authz-ext \
   --source=iap-request-authz-extension.yaml \
   --location=LOCATION

  2. 同じプロジェクトで、決定を拡張機能に委任する認可ポリシーを構成します。

    1. my-iap-authz-request-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 beta network-security authz-policies import コマンドを使用します。

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

Model Armor に認可を委任する

認可ポリシーのコンテンツ セキュリティの決定を Model Armor に委任するように、認可拡張機能を構成できます。

次の例は、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 テンプレートがゲートウェイとは異なるプロジェクトにある場合は、必要なロールを Agent Gateway サービス アカウントに手動で付与する必要があります。サービス アカウントの形式は service-PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com です。ここで、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.iam.gserviceaccount.com \
 --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
 --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
 --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
 --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
 --role=roles/modelarmor.user

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

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

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

gcloud

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

  2. Model Armor テンプレートがゲートウェイとは異なるプロジェクトにある場合は、必要なロールを Agent Gateway サービス アカウントに手動で付与する必要があります。サービス アカウントの形式は service-PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com です。ここで、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.iam.gserviceaccount.com \
 --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
 --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
 --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
 --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
 --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: true
timeout: 1s
EOF

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

      gcloud beta 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 をエージェント ゲートウェイに関連付ける認可ポリシーを定義します。

      cat >ma-content-authz-policy.yaml <<EOF
name: my-ma-content-authz-policy
target:
  resources:
    - "projects/PROJECT_ID/locations/LOCATION/gateways/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 beta network-security authz-policies import コマンドを使用します。

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

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

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

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

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

    cat >custom-authz-extension.yaml <<EOF
name: my-custom-authz-ext
service: mycustomauthz.internal.net
failOpen: true
wireFormat: EXT_AUTHZ_GRPC
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: REQUEST_AUTHZ
  action: CUSTOM
  customProvider:
  authzExtension:
    resources:
    - projects/PROJECT_ID/locations/LOCATION/authzExtensions/custom-authz-extension
  EOF

  4. 認可ポリシーを作成します。

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

この例に示すように、REQUEST_AUTHZ プロファイルを使用して認可拡張機能を認可ポリシーに関連付けると、リクエスト ヘッダーが到着したときにのみゲートウェイが拡張機能を呼び出します。リクエストの本文、レスポンス ヘッダー、レスポンスの本文は、認可拡張機能には表示されません。

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

セキュリティを強化するには、REQUEST_AUTHZ ポリシー プロファイルを含む CUSTOM 認可ポリシーと、CONTENT_AUTHZ ポリシー プロファイルを含む別の CUSTOM 認可ポリシーを設定することをおすすめします。

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

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

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

      $ cat >iap-extension.yaml <<EOF
name: iap-extension
service: iap.googleapis.com
failOpen: true
EOF

    2. 認可拡張機能を作成します。

      gcloud beta 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: エージェント ゲートウェイの名前。

    4. 認可ポリシーを作成します。

      gcloud beta 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: true
timeout: 1s
EOF

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

      • LOCATION: Model Armor テンプレートが存在するリージョン。
      • MODEL_ARMOR_PROJECT_ID: Model Armor テンプレートを含むプロジェクト ID。
      • RESPONSE_TEMPLATE_ID: レスポンス テンプレートの ID。
      • REQUEST_TEMPLATE_ID: リクエスト テンプレートの ID。

    2. 認可拡張機能を作成します。

      gcloud beta 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 beta network-security authz-policies import ma-authz-policy \
--source=authz-policy-content-authz.yaml \
--location=LOCATION

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

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

エージェント ゲートウェイは、リクエスト内の 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 ポリシーの例

    この例では、エージェント ゲートウェイの背後にある MCP サーバーへのすべてのプロンプト/ メソッド アクセスを禁止しています。

    $ 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 beta 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: リソースのロケーション。

制限事項

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

  • ポリシー プロファイルに関係なく、エージェント ゲートウェイごとに最大 4 つのカスタム認可ポリシーを構成できます。
  • CONTENT_AUTHZ プロファイルでカスタム認可拡張機能を使用する場合は、ext_proc プロトコルとボディ イベントの FULL_DUPLEX_STREAMED モードをサポートする必要があります。
  • 同じプロファイルを使用する複数のカスタム認可ポリシーを構成した場合、実行順序は保証されません。

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

次のステップ

ガイド

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