このページでは、サービス拡張機能を使用して、Agent Gateway の認可を Identity-Aware Proxy、Model Armor、その他のカスタム認可エンジンに委任する方法について説明します。
認可ポリシーを使用すると、Agent Gateway によって公開されたエンドポイントを通過するトラフィックに、一元化されたアクセス制御ポリシーとガバナンス ポリシーを適用できます。これらのポリシーを使用すると、mTLS ID、リクエストとレスポンスの属性に基づいてアクセスを制御することでトラフィックを管理できます。また、使用するプロトコル固有の属性(MCP サーバーなど)に基づいてカスタマイズすることもできます。
認可ポリシーは、ポリシー プロファイルを使用して、実行する認可のタイプを決定します。 HTTP リクエスト ヘッダーの情報に依存するリクエストベースの認可ポリシー(REQUEST_AUTHZ)を使用して、トラフィックを許可または拒否できます。また、トラフィックを許可または拒否するためにアプリケーション
ペイロードの詳細な検査を行う必要がある場合は、コンテンツベースの認可ポリシー(CONTENT_AUTHZ)を使用できます。
認可ポリシー、ポリシー プロファイル、ユースケースの詳細については、 認可ポリシー の概要をご覧ください。
認可拡張機能
認可ポリシーを使用して複雑な認可の決定を簡単に表現できない場合があります。Agent Gateway では、認可拡張機能を使用して認可ポリシーを構成し、認可の決定をカスタム認可エンジンに委任できます。
認可拡張機能を使用すると、Agent Gateway デプロイを通過するリクエストをインターセプトして評価できます。管理する外部サービスに対してリアルタイムの gRPC 呼び出しを行うため、トラフィックが宛先に到達する前に検査、変更、ブロックできます。
拡張機能は、構成された 認可 ポリシーに基づいてデータを検査します。認可拡張機能は、リクエストベースとコンテンツベースの認可ポリシーに対して個別に構成することも、包括的なセキュリティのために両方を使用することもできます。
始める前に
始める前に、次の要件を満たしていることを確認してください。
Agent Gateway がデプロイされている。Agent Gateway を構成するをご覧ください。
ゲートウェイに認可ポリシーを適用するには、デプロイされた Agent Gateway リソースに対する
agentGateway.useIAM 権限が必要です。
拡張機能を使用して認可ポリシーを構成する
このセクションでは、認可とコンテンツの安全性の判断を Identity-Aware Proxy、Model Armor、その他のカスタム サービスに委任する認可ポリシーを構成する方法について説明します。
IAP に認可を委任する
リクエスト認可拡張機能を構成して、認可ポリシーのアクセス決定を IAP に委任できます。
次の手順では、Agent Gateway インスタンスの認可ポリシーを使用して認可拡張機能を構成する方法について説明します。
エージェントとツールに必要な IAM 下り(外向き)ポリシーを作成します。詳細については、IAM エージェント ポリシーを作成するをご覧ください。
Agent Gateway の作成時に([**アクセス認可**] パラメータを使用して)IAP を有効にするには、エージェントから任意の宛先へ(外向き) モードで Agent Gateway を構成するをご覧ください。
IAP では、エージェントがゲートウェイにバインドされたエージェント レジストリ リソースに登録されている必要があります。
IAP を指すように認可拡張機能を構成します。
YAML ファイルで拡張機能を定義します。提供されているサンプル値を使用します。拡張機能をドライラン モード(監査のみ)でデプロイして、認可ポリシーを適用せずにテストする場合は、
metadataブロック内でiamEnforcementModeフィールドを指定します。cat >iap-request-authz-extension.yaml <<EOF name: my-iap-request-authz-ext service: iap.googleapis.com failOpen: true timeout: 1s metadata: iapPolicyVersion: "V1" EOF拡張機能をドライラン モード(監査のみ)でデプロイして、認可ポリシーを適用せずにテストする場合は、
metadataブロック内でiamEnforcementModeフィールドを指定します。 これにより、ポリシーを確認し、構成エラーによるトラフィックの中断のリスクを最小限に抑えることができます。cat >iap-request-authz-extension.yaml <<EOF name: my-iap-request-authz-ext service: iap.googleapis.com failOpen: true timeout: 1s metadata: iapPolicyVersion: "V1" iamEnforcementMode: "DRY_RUN" EOFポリシーの適用を開始する準備ができたら、
metadataブロック からiamEnforcementMode: "DRY_RUN"フィールドを削除します。認可拡張機能をインポートします。次のサンプル値を使用して、
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
同じプロジェクトで、決定を拡張機能に委任する認可ポリシーを構成します。
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" EOFPROJECT_IDは、実際の プロジェクト ID に置き換えます。認可ポリシーをプロジェクトにインポートします。次のサンプル値を使用して、
gcloud 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 の認可ポリシーを使用して、このような認可拡張機能を構成する方法を示しています。
コンソール
コンソールを使用して Agent Gateway の Model Armor を有効にするには、次の操作を行います。 Google Cloud
必要な Model Armor テンプレートを作成します。
Agent Gateway の作成時に([Model Armor を有効にする] チェックボックスを使用して)Model Armor を有効にするには、Agent Gateway を構成するをご覧ください。Model Armor テンプレートは、クライアントからエージェントへモードとエージェントから任意の宛先へモードの両方でサポートされています。
Model Armor を使用する場合は、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 にゲートウェイを使用している場合、推論 エンジン サービス エージェントにも、Agent Gateway を介して Agent Runtime トラフィックをルーティングするで説明されている権限が必要です。
- ゲートウェイを含むプロジェクトの
gcloud
必要な Model Armor テンプレートを作成します。
Model Armor を使用する場合は、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。
- ゲートウェイを含むプロジェクトの
Model Armor を指すように認可拡張機能を構成します。
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認可拡張機能をインポートします。次のサンプル 値を使用して、
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
拡張機能を使用して認可ポリシーを構成します。
拡張機能
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/gateways/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/gateways/AGENT_GATEWAY_NAME" policyProfile: CONTENT_AUTHZ action: CUSTOM customProvider: authzExtension: resources: - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/my-ma-content-authz-ext" EOFpolicyProfileの値はCONTENT_AUTHZに設定されています。これは、カスタム ポリシー プロバイダがリクエスト本文を含むリクエストとレスポンスのトラフィックを処理することを示します。認可ポリシーをプロジェクトにインポートします。次のサンプル値を使用して、
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
カスタム認可拡張機能に認可を委任する
カスタム認可拡張機能を構成して、決定をカスタム サービスに委任できます。これらのカスタム拡張機能は、完全修飾ドメイン名(FQDN)のみをターゲットにできます。
FQDN ターゲットを使用する場合、拡張機能は TLS 暗号化で HTTP2 プロトコルを使用してポート 443 のエンドポイントと通信します。ただし、拡張機能はサーバー証明書を検証しません。 そのため、セキュリティを強化するには、解決されたエンドポイントが VPC ネットワーク内にあることを確認する必要があります。また、Agent Gateway プロジェクトと VPC ネットワークの間に DNS ピアリングが設定されていることを確認してください。
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 timeout: 1s wireFormat: EXT_AUTHZ_GRPC EOFカスタム サービスを指す認可拡張機能を作成します。
gcloud beta service-extensions authz-extensions import custom-authz-extension \ --source=custom-authz-extension.yaml \ --location=LOCATION
拡張機能を作成したら、決定を認可拡張機能に委任する
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認可ポリシーを作成します。
gcloud 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 ガードレールとして使用しています。前の例に示すように、これらの各サービスをサービス拡張機能に置き換えて、独自のカスタム ソリューションを使用できます。
IAP に委任する
REQUEST_AUTHZ認可拡張機能と、拡張機能を指す認可ポリシーを構成します。認可拡張機能を定義します。 の
iapPolicyVersionフィールドは必須で、"V1"に設定する必要があります。metadatacat >iap-extension.yaml <<EOF name: iap-extension service: iap.googleapis.com failOpen: true timeout: 1s metadata: iapPolicyVersion: "V1" EOF認可拡張機能を作成します。
gcloud service-extensions authz-extensions import iap-extension \ --source=iap-extension.yaml \ --location=LOCATION
LOCATIONは、拡張機能のリージョンに置き換えます。拡張機能に委任する
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 の名前。
認可ポリシーを作成します。
gcloud network-security authz-policies import authz-iap \ --source=authz-policy-request-authz.yaml \ --location=LOCATION
Model Armor に委任する
CONTENT_AUTHZ認可拡張機能と、拡張機能を指す認可ポリシーを構成します。拡張機能を定義します。
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。
認可拡張機能を作成します。
gcloud service-extensions authz-extensions import ma-extension \ --source=ma-extension-file.yaml \ --location=LOCATION
拡張機能に委任する
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認可ポリシーを作成します。
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 つの例を示します。
認可ポリシーを構成します。
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 EOFDENYポリシーの例この例では、Agent Gateway の背後にある 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認可ポリシーを作成します。
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: リソースのロケーション。
制限事項
認可ポリシーを使用する場合は、次の制限事項が適用されます。
- エージェントから任意の宛先へ(外向き)ゲートウェイの場合、ポリシー プロファイルに関係なく、ゲートウェイごとに最大 4 つのカスタム認可ポリシーを構成できます。
- クライアントからエージェントへ(内向き)ゲートウェイの場合、構成できる
CONTENT_AUTHZポリシーは 1 つだけです。プロンプト インジェクション攻撃から保護するには、Model Armor を使用することを強くおすすめします。 ただし、代わりにセマンティック ガバナンス ポリシー拡張機能を使用する場合は、ゲートウェイで Model Armor が構成されていないことを確認する必要があります。他のタイプのサービス拡張機能は、上り(内向き)ではサポートされていません。 CONTENT_AUTHZプロファイルでカスタム認可拡張機能を使用する場合は、本文イベントのext_procプロトコルとFULL_DUPLEX_STREAMEDモードをサポートする必要があります。- 同じプロファイルを使用する複数のカスタム認可ポリシーを構成した場合、実行順序は保証されません。
また、認可拡張機能の制限事項の詳細については、次のセクションをご覧ください。
すべての拡張機能に適用される制限については、 拡張機能の制限事項をご覧ください。
コールアウトに適用される制限については、 コールアウトの制限事項をご覧ください。
次のステップ
Codelab: Agent Platform でエージェント ワークロードを管理する
Gemini Enterprise Agent Platform で Agent Gateway を使用してエージェント ワークロードを管理する方法を学習します。