排解 IAM 統一存取政策問題

本文說明如何診斷及解決設定及強制執行 Agent Gateway 輸出作業的 IAM 統一存取政策 (UAP) 時遇到的常見問題。

政策違規處置和存取失敗

本節說明違規處置相關問題。

未強制執行政策

症狀：即使已設定 IAM 拒絕規則或限制性允許規則來封鎖存取，代理仍可存取目的地工具、MCP 伺服器或端點。

原因：Agent Gateway 授權擴充功能在模擬測試模式下執行，或政策繫結範圍與目標資源不符。在模擬測試模式下，系統會評估存取權決策並記錄下來，以供稽核，但不會封鎖要求。

解決方法：

  1. 將模擬測試模式切換為強制執行模式：首先，請檢查授權擴充功能設定檔 (iap-request-authz-extension.yaml)。如果 iamEnforcementMode 設為 "DRY_RUN"，請更新為 "ENFORCE" (或移除 DRY_RUN 設定)，然後使用 gcloud CLI 重新匯入擴充功能：

    gcloud service-extensions authz-extensions import EXTENSION_NAME \
    --source=EXTENSION_FILE.yaml \
    --location=LOCATION

    更改下列內容：

    • EXTENSION_NAME：授權擴充功能的名稱
    • EXTENSION_FILE：YAML 擴充功能設定的檔案名稱
    • LOCATION：閘道部署所在的 Google Cloud 區域

  2. 驗證閘道授權政策委派：確認閘道授權政策 (policyProfile: REQUEST_AUTHZ) 已繫結至正確的 Agent Gateway 執行個體 (target.resources)。

  3. 檢查政策繫結範圍：確認 IAM UAP 已繫結至流量抵達的目標資源範圍。

  4. 檢查規則優先順序：在組合政策中，拒絕規則會明確覆寫相同範圍內的允許規則。不過，請檢查在登錄檔或專案層級繫結、允許規則較寬鬆的 UAP，是否在沒有條件限制的情況下授予存取權。

違規處置政策會封鎖代理存取權

症狀：啟用 Agent Gateway 政策強制執行功能時，代理的輸出要求失敗，並顯示 HTTP 403 Forbidden 或 PERMISSION_DENIED 錯誤。

原因：

  • UAP 未指定代理的身分。

  • 代理程式的身分未獲得目的地資源的 iap.resources.egressViaIAP 權限。

  • 確切的目的地主機名稱未在代理程式註冊資料庫中註冊

  • 要求屬性不符合 UAP 中的一般運算語言 (CEL) 條件。

解決方法：

  1. 切換至模擬測試模式，進行不中斷的偵錯：診斷失敗時，請暫時將授權擴充功能切換至「模擬測試模式」 (iamEnforcementMode: "DRY_RUN")，這樣在檢查稽核記錄時，就不會封鎖有效的代理流量。

  2. 查詢 Cloud 稽核記錄：查詢 Cloud 稽核記錄，檢查確切的授權檢查和 CEL 屬性評估：

    gcloud

    執行下列 gcloud logging read 指令：

    gcloud logging read \
    'protoPayload.serviceName="iap.googleapis.com" AND protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP" AND protoPayload.status.code!=0' \
    --project=PROJECT_ID \
    --limit=20

    將 PROJECT_ID 替換為專案 ID。

    控制台

    1. 前往 Google Cloud 控制台的「Logs Explorer」頁面。
    2. 選取專案。
    3. 在查詢編輯器中輸入下列查詢： 
          protoPayload.serviceName="iap.googleapis.com"
    protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP"
    protoPayload.status.code!=0
    4. 點選「執行查詢」。
    5. 展開記錄項目並檢查 protoPayload.authorizationInfo，查看哪些目標資源 URI 和權限未通過評估。

  3. 確認主機名稱完全相符：Agent Gateway 會比對完全相符的目的地主機名稱。Google API 或第三方服務可能會根據 SDK 版本、區域用戶端設定或 mTLS 使用情形，透過多種主機名稱變化版本解析，例如 us-central1-aiplatform.googleapis.com、us-central1-aiplatform.mtls.googleapis.com 和 aiplatform.googleapis.com。

    • 如果您依賴已註冊的目標，請務必在代理程式註冊表中註冊每個確切的主機名稱變化版本。
    • 如果代理存取未註冊的端點，請確認未註冊的端點政策為該主機和路徑授予 iap.resources.egressViaIAP。

  4. 確認各範圍的政策繫結涵蓋範圍：檢查三個支援範圍之一是否存在政策繫結：

    • 整個儲存庫：授予儲存庫中所有代理、MCP 伺服器和端點的存取權。
    • 依資源：授予特定已註冊 MCP 伺服器、端點或代理的存取權。
    • 未註冊的端點：授予 Agent Registry 外部目的地的存取權。
    • 注意：說明目標資源的政策繫結時，如果傳回的輸出內容包含 "etag" 欄位，但沒有繫結，表示該目標沒有 IAM 政策。

  5. 驗證 CEL 條件屬性值：比較 Cloud 稽核記錄中記錄的要求屬性值，與 UAP 條件運算式中的常值：

    • 區分大小寫的字串比對：CEL 條件中的字串比較會區分大小寫。確認複製或輸入的值 (例如 MCP 工具名稱 (destination.agent_registry.mcp_server.tool.name)、MCP 伺服器或代理資源名稱 (destination.agent_registry.mcp_server.name、destination.agent_registry.agent.name) 或 HTTP 方法 (destination.unregistered.method)) 與要求中的大小寫和拼寫完全一致。
    • 未註冊目的地的不同主機和路徑：如果輸出目的地包含通訊埠 (例如 destination.unregistered.host 搭配 example.com:443)、子網域或變數網址路徑 (destination.unregistered.path)，除非完整字串相符，否則完全相等檢查 (==) 會失敗。如果是 destination.unregistered.host 和 destination.unregistered.path，您可以使用 .startsWith()、.endsWith() 或 .contains()，而非完全相等 (==)：
      • 使用 .startsWith() 依前置字元篩選網址路徑 (例如 destination.unregistered.path.startsWith('/v2/process'))。
      • 使用 .endsWith() 授予或拒絕存取權，適用於共用指定後置字串 (例如 destination.unregistered.host.endsWith('.example.com')) 的所有子網域。

常見的使用者介面、gcloud 和 REST API 錯誤訊息

本節說明錯誤訊息和解決方法。

找不到政策

錯誤訊息：

  • 控制台 UI：「The requested policy doesn't exist. 請確認所選資源有這項政策。
  • API/gcloud：POLICY_NOT_FOUND/HTTP 404 Not Found

原因：更新要求或政策繫結中指定的 UAP ID 不存在於專案或位置，或已刪除。

解決方案：使用 gcloud iam access-policies list --project=<var>PROJECT_ID</var> --location=global 列出專案中所有可用的 UAP，確認確切的政策 ID 和位置，再進行繫結或更新。

超過目標繫結限制

錯誤訊息：

  • 控制台 UI：「所選目標的存取政策繫結數量已達上限。請先刪除現有繫結，再新增繫結。
  • API/gcloud：TOO_MANY_ACCESS_POLICY_BINDINGS_PER_TARGET

原因：您嘗試附加至目標資源 (例如 MCP 伺服器或登錄檔) 的政策繫結數量，超過每個目標允許的上限。

解決方案：請勿為每項規則建立個別 UAP 和繫結，而是將多項允許或拒絕規則合併為單一 UAP。使用 gcloud iam policy-bindings delete 移除未使用的繫結。

超過政策繫結限制

錯誤訊息：

  • 控制台 UI：「所選政策的繫結數量已達上限。請先刪除現有繫結，再新增繫結。
  • API/gcloud：TOO_MANY_ACCESS_POLICY_BINDINGS_TO_POLICY

原因：單一 UAP 附加至專案中過多不同的目標資源。

解決方法：在更廣泛的範圍 (例如整個登錄檔範圍 (AgentRegistry) 或專案範圍) 繫結政策，並使用 CEL 屬性條件 (例如 destination.agent_registry.mcp_server.name) 控管政策規則中個別工具的存取權。

超出條件上限

錯誤訊息：

  • 控制台 UI：「這項政策的屬性條件數量已達上限。請移除部分條件，才能儲存變更。」
  • API/gcloud：TOO_MANY_CONDITIONS/政策中的規則超出條件限制。

原因：單一允許或拒絕規則包含的精細存取控管 (FGAC) 屬性條件或複雜子運算式，超過單一規則支援的數量。

解決方法：使用 CEL 邏輯運算子 (&&、||) 或集合包含查詢 (in) 整合屬性檢查，或將運算式拆分到同一 UAP 內的多項規則。

規則詳細資料已過時

錯誤訊息：

  • 控制台 UI：「規則詳細資料已過時。這個頁面載入之後，其他使用者修改了這項規則。請先重新整理頁面，擷取目前的詳細資料，再編輯或刪除。
  • API/gcloud：HTTP 412 Precondition Failed/ABORTED，因為 etag 不符。

原因：您擷取 UAP 後，其他管理員或自動化程序修改了 UAP，導致要求的 etag 與有效伺服器狀態不同。

解決方案：重新整理控制台頁面，擷取有效的政策詳細資料和 etag，然後再儲存編輯內容。使用 REST API 時，請先執行 GET 要求來擷取有效的 "etag" 值，並將其納入 PATCH 要求酬載中。

無法刪除政策中的最後一項規則

錯誤訊息：

  • 控制台 UI：「無法刪除這項規則。「預設政策」至少須有一項規則。如要移除這項規則，請改為刪除政策。或「這是 <政策名稱> 的最後一項規則。如果刪除，系統也會刪除政策，並永久移除所有相關繫結，這可能會影響代理程式對資源的存取權。」

原因：IAM UAP 必須至少有一項規則，才能儲存。

解決方案：如要移除政策中唯一的規則，請刪除整個政策。請注意，您必須先刪除所有參照政策的政策繫結，才能刪除政策本身。

「進階」分頁中保留的自訂 CEL 運算式

錯誤訊息：

  • 控制台 UI：「The custom CEL expression could not be converted into standard UI selections. 您的運算式會保留在「進階」分頁中。

原因：您在「Condition editor」(條件編輯器) (「Advanced」(進階) 分頁) 中輸入複雜的 CEL 條件或函式，無法對應至標準條件建構工具的簡化下拉式選取器。

解決方案：這則訊息是資訊通知，自訂 CEL 條件有效且會保留。繼續在「Condition editor」(條件編輯器) 分頁中直接編輯。

無法對目標屬性呼叫函式

錯誤訊息：

  • API/gcloud：Function '<var>FUNCTION_NAME</var>' cannot be called on the target '<var>ATTRIBUTE_NAME</var>' in namespace 'iap.googleapis.com'. (錯誤代碼 3/INVALID_ARGUMENT)

原因：政策規則條件對不支援該函式的屬性使用 CEL 函式 (例如 .startsWith()、.endsWith() 或 .contains())，或嘗試對布林值屬性或不支援的欄位呼叫字串函式。在 UAP 中，字串比對函式僅支援 destination.unregistered.host 和 destination.unregistered.path。

解決方案：更新 CEL 條件運算式，僅對目標屬性使用支援的運算：

  • 未註冊的主機和路徑屬性 (destination.unregistered.host、destination.unregistered.path)：使用 ==、!=、in、.startsWith()、.endsWith() 或 .contains()。
  • 其他字串屬性 (destination.unregistered.method 和 destination.agent_registry.* 字串屬性)：使用 ==、!= 或 in。
  • 布林值屬性 (例如 destination.is_registered、工具註解)：使用邏輯比較 (==、!=)。

如需完整的屬性和支援作業清單，請參閱「UAP 的 CEL 屬性」。

政策中指定的使用者不屬於獲准客戶

錯誤訊息：

  • API/gcloud：One or more users named in the policy do not belong to a permitted customer. (錯誤代碼 3/INVALID_ARGUMENT)

原因：根據預設，IAM UAP 會對新增至 ALLOW 規則的主體，強制執行內建且無法設定的網域限制共用 (DRS)。ALLOW 規則的 principals 陣列中指定的一或多個主體身分 (例如 Agent Identity、Workload Identity、使用者身分或服務帳戶)，與建立或更新政策的專案不屬於同一個 Google Cloud組織。這項內建檢查不依賴組織政策限制 (例如 constraints/iam.allowedPolicyMemberDomains 或 constraints/iam.managed.allowedPolicyMembers)，且無法停用。

解決方案：檢查政策設定檔 (例如在 gcloud iam access-policies create 或 update 中以 --details-rules 旗標指定的 JSON 或 YAML 檔案) ALLOW 規則中的 principals 陣列。移除所有外部主體，並確保所有指定的主體身分都屬於與專案相同的 Google Cloud 組織。

後續步驟