Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用 Service Extensions 委派授權

本頁說明如何使用 Service Extensions，將 Agent Gateway 的授權委派給 Identity-Aware Proxy、Model Armor 和其他自訂授權引擎。

授權政策可讓您對通過 Agent Gateway 發布端點的流量，強制執行集中式存取控管和管理政策。您可以透過這些政策，根據 mTLS 身分、要求和回應屬性控管存取權，藉此管理流量，甚至根據所用的通訊協定專屬屬性 (例如 MCP 伺服器) 自訂政策。

授權政策會使用政策設定檔，判斷要執行的授權類型。您可以根據 HTTP 要求標頭中的資訊，使用以要求為準的授權政策 (REQUEST_AUTHZ) 允許或拒絕流量。或者，您也可以使用以內容為準的授權政策 (CONTENT_AUTHZ)，深入檢查應用程式酬載，以允許或拒絕流量。

如要進一步瞭解授權政策、政策設定檔及其用途，請參閱「授權政策總覽」。

授權擴充功能

有時，複雜的授權決策無法輕易以授權政策表示。您可以透過 Agent Gateway，使用授權擴充功能設定授權政策，將授權決策委派給自訂授權引擎。

授權擴充功能可攔截並評估通過 Agent Gateway 部署作業的要求。這項功能會對您管理的外部服務發出即時 gRPC 呼叫，讓您檢查、修改甚至封鎖流量，避免流量繼續傳輸至目的地。

擴充功能會根據設定的授權政策檢查資料。您可以分別為要求型和內容型授權政策設定授權擴充功能，也可以同時使用這兩種政策，全面提升安全性。

事前準備

開始前，請確認符合下列條件：

Agent Gateway 已部署完成。請參閱「設定代理程式閘道」。
您必須擁有已部署 Agent Gateway 資源的 agentGateway.use IAM 權限，才能將授權政策附加至閘道。

使用擴充功能設定授權政策

本節說明如何設定授權政策，將授權和內容安全決策委派給 Identity-Aware Proxy、Model Armor 和其他自訂服務。

將授權委派給 IAP

您可以設定要求授權擴充功能，將授權政策的存取權決策委派給 IAP。

下列步驟說明如何為 Agent Gateway 執行個體設定授權擴充功能和授權政策。

為代理程式和工具建立必要的 IAM 輸出政策。詳情請參閱「建立 IAM 代理程式政策」。
如要在建立 Agent Gateway 時啟用 IAP (使用「存取授權」參數)，請參閱「在 Agent-to-Anywhere (Egress) 模式中設定 Agent Gateway」。

IAP 規定代理程式必須向繫結至閘道的代理程式登錄資源註冊。
設定授權擴充功能，指向 IAP。
1. 在 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" 欄位。
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
```

在同一個專案中，設定授權政策，將決策委派給擴充功能。

定義授權政策，將 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 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，請按照下列步驟操作：

建立必要的 Model Armor 範本。
如要啟用 Model Armor，請參閱「設定 Agent Gateway」，並在建立 Agent Gateway 時勾選「啟用 Model Armor」核取方塊。Client-to-Agent 和 Agent-to-Anywhere 模式都支援 Model Armor 範本。
使用 Model Armor 時，您必須授予 Agent Gateway 服務帳戶使用 Model Armor 範本所需的權限。服務帳戶的格式為：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 Service Agent 也需要這些權限，詳情請參閱「透過 Agent Gateway 路由 Agent Runtime 流量」。

gcloud

建立必要的 Model Armor 範本。
使用 Model Armor 時，您必須授予 Agent Gateway 服務帳戶使用 Model Armor 範本所需的權限。服務帳戶的格式為：service-PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com，其中 PROJECT_NUMBER 是您建立閘道的專案專案編號。

即使閘道和範本位於同一個專案中，仍必須完成這個步驟。授予下列角色：
- 包含閘道的專案中的 roles/modelarmor.calloutUser 和 roles/serviceusage.serviceUsageConsumer 角色。
- 專案中的 roles/modelarmor.user 角色，該專案包含 Model Armor 範本。
```
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

使用擴充功能設定授權政策。

定義授權政策，將擴充功能與 Agent Gateway 建立關聯。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"
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"
EOF

policyProfile 的值已設為 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 目標時，擴充功能會使用 HTTP2 通訊協定和 TLS 加密，與通訊埠 443 上的端點通訊。不過，擴充功能不會驗證伺服器憑證。因此，為確保安全性，您必須確認解析的端點位於虛擬私有雲網路內。此外，請確認您已在 Agent Gateway 專案和虛擬私有雲網路之間設定 DNS 對接。

如要為特定 FQDN (例如 mycustomauthz.internal.net) 設定授權政策的授權擴充功能，請在擴充功能 YAML 檔案中，將該 FQDN 指定為 service 的值，如下列範例所示。本範例假設您已在 VPC 網路中部署伺服器，並以 FULL_DUPLEX_STREAMED 主體處理模式實作 ext_proc 通訊協定。
```
cat >custom-authz-extension.yaml <<EOF
name: my-custom-authz-ext
service: mycustomauthz.internal.net
failOpen: true
timeout: 1s
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: CONTENT_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

請注意，當授權擴充功能與授權政策建立關聯時 (如本範例所示，使用 CONTENT_AUTHZ 設定檔)，閘道會針對要求和回應酬載 (標頭和主體) 叫用擴充功能，以便深入檢查內容、提供提示防護措施，以及對代理程式流量進行資料清除。根據預設，CONTENT_AUTHZ 政策會使用 FULL_DUPLEX_STREAMED 模式的 Envoy ext_proc 通訊協定處理主體事件。

將 IAP 授權與 Model Armor 防護機制結合

為確保全面安全，建議您使用 REQUEST_AUTHZ 政策設定檔設定自訂授權政策，並使用 CONTENT_AUTHZ 政策設定檔設定另一項自訂授權政策。

下列範例使用 IAP 做為集中式要求授權系統，並使用 Model Armor 做為 AI 防護措施。如先前範例所示，您可以將這些項目換成服務擴充功能，使用自己的自訂解決方案。

設定授權擴充功能 (委派給 IAP) 和指向該擴充功能的授權政策。REQUEST_AUTHZ

定義授權擴充功能。metadata 底下的 iapPolicyVersion 欄位為必填欄位，且必須設為 "V1"。

cat >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)。

如要瞭解如何佈建政策引擎，並在閘道上建立必要的授權政策和授權擴充功能繫結，請參閱「將政策引擎連線至 Agent Gateway」。CONTENT_AUTHZ

根據 MCP 通訊協定屬性授權

Agent Gateway 會剖析要求中的 MCP 通訊協定酬載，並將擷取的屬性用於授權政策。

您可以根據 MCP 方法參數 (例如特定工具的名稱) 限制存取權。本節提供兩個範例，分別說明 ALLOW 政策和 DENY。

設定授權政策。

ALLOW 政策範例

這個範例允許存取 MCP 伺服器和基本通訊協定功能上的一組特定工具，但不允許存取提示和資源。

撰寫 ALLOW 政策時，請務必指定 baseProtocolMethodsOption: MATCH_BASE_PROTOCOL_METHODS，確保初始化、記錄、完成、通知和 Ping 等非存取專屬的 MCP RPC 仍可運作。否則將無法建立 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 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：資源的位置。

限制

使用授權政策時，請注意下列限制：

如果是「代理程式到任何位置」(輸出) 閘道，無論政策設定檔為何，每個閘道最多可設定四項自訂授權政策。
對於「用戶端到代理程式」(連入) 閘道，您最多可以設定一項 CONTENT_AUTHZ 政策。強烈建議使用 Model Armor 防範提示詞注入式攻擊。不過，如要改用 Semantic Governance Policy 擴充功能，請務必確認閘道上未設定 Model Armor。系統不支援其他類型的服務擴充功能。
如果您使用自訂授權擴充功能搭配 CONTENT_AUTHZ 設定檔，這些擴充功能必須支援 ext_proc 通訊協定和 FULL_DUPLEX_STREAMED 模式，才能處理主體事件。
如果設定多項使用相同設定檔的自訂授權政策，系統不保證執行順序。

此外，如要進一步瞭解授權擴充功能的限制，請參閱下列各節：

如要瞭解所有擴充功能適用的限制，請參閱「擴充功能的限制」。
如要瞭解宣傳文字適用的限制，請參閱「宣傳文字的限制」。

後續步驟

程式碼研究室

使用 Service Extensions 委派授權

授權擴充功能

事前準備

使用擴充功能設定授權政策

將授權委派給 IAP

將授權委派給 Model Armor

控制台

gcloud

代理至任意目的地

用戶端至代理

將授權委派給自訂授權擴充功能

將 IAP 授權與 Model Armor 防護機制結合

將授權委派給語意管理政策

根據 MCP 通訊協定屬性授權

限制

後續步驟

程式碼研究室：使用 Agent Platform 管理代理程式工作負載

Agent Gateway

排解 Agent Gateway 問題

使用 Service Extensions 委派授權 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

授權擴充功能

事前準備

使用擴充功能設定授權政策

將授權委派給 IAP

將授權委派給 Model Armor

控制台

gcloud

代理至任意目的地

用戶端至代理

將授權委派給自訂授權擴充功能

將 IAP 授權與 Model Armor 防護機制結合

將授權委派給語意管理政策

根據 MCP 通訊協定屬性授權

限制

後續步驟

程式碼研究室：使用 Agent Platform 管理代理程式工作負載

Agent Gateway

排解 Agent Gateway 問題

使用 Service Extensions 委派授權