Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

このページでは、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 がデプロイされている。Agent Gateway を構成するをご覧ください。
ゲートウェイに認可ポリシーを適用するには、デプロイされた Agent Gateway リソースに対する agentGateway.use IAM 権限が必要です。

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

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

IAP に認可を委任する

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

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

エージェントとツールに必要な IAM 下り（外向き）ポリシーを作成します。詳細については、IAM エージェントポリシーを作成するをご覧ください。
Agent Gateway を作成するときに（[Access authorization] パラメータを使用して）、Agent-to-Anywhere（下り（外向き））モードで Agent Gateway を構成するの手順に沿って IAP を有効にします。

IAP では、エージェントがゲートウェイにバインドされた Agent Registry リソースに登録されている必要があります。
IAP を指すように認可拡張機能を構成します。
1. YAML ファイルで拡張機能を定義します。提供されているサンプル値を使用します。
```
cat >iap-request-authz-extension.yaml <<EOF
name: my-iap-request-authz-ext
service: iap.googleapis.com
failOpen: true
timeout: 1s
EOF
```
  拡張機能をドライランの監査専用モードでデプロイして、認可ポリシーを適用せずにテストする場合は、DRY_RUN フィールドを指定します。これにより、ポリシーを確認し、構成エラーによるトラフィックの中断のリスクを最小限に抑えることができます。
```
cat >iap-request-authz-extension.yaml <<EOF
name: my-iap-request-authz-ext
service: iap.googleapis.com
failOpen: true
timeout: 1s
metadata:
  iamEnforcementMode: "DRY_RUN"
EOF
```
  ポリシーの適用を開始する準備ができたら、DRY_RUN メタデータフィールドを削除します。
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
```

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

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 に置き換えます。

認可ポリシーをプロジェクトにインポートします。次のサンプル値を使用して、 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 の認可ポリシーを使用して、このような認可拡張機能を構成する方法を示しています。

コンソール

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

必要な Model Armor テンプレートを作成します。
Agent Gateway を作成するときに（[Enable Model Armor] チェックボックスを使用して）、Agent Gateway を構成するの手順に沿って Model Armor を有効にします。Model Armor テンプレートは、Client-to-Agent モードと Agent-to-Anywhere モードの両方でサポートされています。
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 テンプレートがゲートウェイとは異なるプロジェクトにある場合は、必要なロールを 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 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
```

拡張機能を使用して認可ポリシーを構成します。
1. 拡張機能 my-ma-content-authz-ext を Agent Gateway に関連付ける認可ポリシーを定義します。
  Agent-to-Anywhere
  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 呼び出しなどの内部トラフィックを除外できます。
  Client-to-Agent
  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 ネットワーク内にあることを確認する必要があります。また、Agent Gateway プロジェクトと VPC ネットワークの間に DNS ピアリングが設定されていることを確認してください。

特定の FQDN（mycustomauthz.internal.net など）の認可ポリシーを使用して認可拡張機能を構成するには、次の例に示すように、拡張機能の 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 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 ガードレールとして使用しています。前の例に示すように、これらの各サービスをサービス拡張機能に置き換えて、独自のカスタムソリューションを使用できます。

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

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

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

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

gcloud beta 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 beta 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 beta 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 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 ポリシープロファイルを使用して単一のCUSTOM認可ポリシーを構成することをおすすめします。このポリシーは、汎用性の高い認可拡張機能を指す必要があります。このアプローチでは、単一の拡張機能と ext_proc 接続を介して両方のタイプの認可が可能になります。これにより、REQUEST_AUTHZ プロファイルと CONTENT_AUTHZ プロファイルに別々の拡張機能を使用する場合と比較して、レイテンシを改善できます。

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

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

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

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

ALLOW ポリシーの例

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

ALLOW ポリシーを作成する場合は、initialize、logging、completion、notifications、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 サーバーへのすべてのプロンプト/ メソッドアクセスを禁止します。

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

制限事項

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

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

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

すべての拡張機能に適用される制限については、拡張機能の制限事項をご覧ください。
コールアウトに適用される制限については、コールアウトの制限事項をご覧ください。

次のステップ

ガイド

Agent Gateway をモニタリングする

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

Service Extensions を使用して認可を委任する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

認可拡張機能

始める前に

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

IAP に認可を委任する

Model Armor に認可を委任する

コンソール

gcloud

Agent-to-Anywhere

Client-to-Agent

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

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

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

制限事項

次のステップ

Agent Gateway をモニタリングする

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