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 身分、要求和回應屬性控管存取權，藉此管理流量，甚至根據所用的通訊協定專屬屬性 (例如 MCP 伺服器) 自訂政策。

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

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

授權擴充功能

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

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

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

事前準備

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

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

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

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

將授權委派給 IAP

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

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

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

IAP 規定代理程式必須向繫結至閘道的代理程式登錄資源註冊。
設定授權擴充功能，指向 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 設定這類授權擴充功能和授權政策。

控制台

如要透過 Google Cloud 控制台為 Agent Gateway 啟用 Model Armor，請按照下列步驟操作：

建立必要的Model Armor 範本。
請參閱「設定代理閘道」，瞭解如何在建立代理閘道時啟用 Model Armor (勾選「啟用 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，Reasoning Engine 服務代理程式也需要這些權限，詳情請參閱「透過 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 角色。
- 專案中的 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 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

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

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

如要為特定 FQDN (例如 mycustomauthz.internal.net) 設定授權政策的授權擴充功能，請在擴充功能 YAML 檔案中，將該 FQDN 指定為 service 的值，如下列範例所示。這個範例假設您已在 VPC 網路中部署實作 ext_authz 通訊協定的伺服器。
```
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 政策設定檔設定自訂授權政策，並使用 CONTENT_AUTHZ 政策設定檔設定另一項自訂授權政策。

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

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

定義授權擴充功能。

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：代理程式閘道的名稱。

建立授權政策。

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。

設定授權政策。

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 政策範例

這個範例會禁止所有提示/ 方法存取代理程式閘道後方的 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 最多可設定四項自訂授權政策。
如果您使用自訂授權擴充功能搭配 CONTENT_AUTHZ 設定檔，這些擴充功能必須支援 ext_proc 通訊協定和 FULL_DUPLEX_STREAMED 模式，才能處理主體事件。
如果您設定多項使用相同設定檔的自訂授權政策，系統不保證執行順序。

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

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

後續步驟

指南

監控代理程式閘道

瞭解如何監控 Agent Gateway。

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

授權擴充功能

事前準備

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

將授權委派給 IAP

將授權委派給 Model Armor

控制台

gcloud

代理至任意目的地

用戶端至代理

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

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

根據 MCP 通訊協定屬性授權

限制

後續步驟

監控代理程式閘道

使用 Service Extensions 委派授權