驗證 IAM 政策

本頁內容適用於 Apigee，但不適用於 Apigee Hybrid。

查看 Apigee Edge 說明文件。

總覽

根據 Google Cloud IAM，使用 VerifyIAM 對 API 存取權強制執行授權檢查。這是 OAuthv2 政策和 VerifyAPIKey 政策的替代方案。如要瞭解如何在以 IAM 為基礎的存取權控管解決方案中加入 VerifyIAM，請參閱「以 IAM 為基礎的 API 驗證總覽」。

這項政策屬於標準政策，可部署至任何環境類型。如要瞭解各環境類型適用的政策類型和可用性，請參閱「政策類型」。

元素參考資料

本參考資料說明 VerifyIAM 政策的元素和屬性。

<VerifyIAM async="false" continueOnError="false" enabled="true" name="MyVerifyIAMPolicy">
    <DisplayName>Custom label used in UI</DisplayName>
    <CredentialSource>flow_variable_name_containing_credential_value</CredentialSource>
</VerifyIAM>

<VerifyIAM> 屬性

<VerifyIAM async="false" continueOnError="false" enabled="true" name="MyVerifyIAMPolicy">

下表說明所有政策父項元素的共同屬性：

屬性 說明 預設 存在必要性
name

政策的內部名稱。name 屬性的值可以包含英文字母、數字、空格、連字號、底線和句號。這個值不得超過 255 個半形字元。

您可以選擇使用 <DisplayName> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。

 不適用 必填
continueOnError

將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。

將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：

 false 選用
enabled

設為 true 即可強制執行政策。

設為 false 即可關閉政策。即使政策仍附加至流程中，也不會強制執行。

 是 選用
async

此屬性已淘汰。

 false 已淘汰

<DisplayName> 元素

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用不同的自然語言名稱標示政策。

<DisplayName>Policy Display Name</DisplayName>
預設

不適用

如果省略這個元素，系統會使用政策的 name 屬性值。
存在必要性 選用
類型 字串

<CredentialSource> 元素

<CredentialSource>flow_variable_name_containing_credential_value</CredentialSource>

這個元素會指定含有憑證值的流程變數，並具有下列特徵：

  • 一般來說，用戶端會透過查詢參數、HTTP 標頭或表單參數傳送值。字串必須以 request.queryparam.token 形式指定對應的流程變數。
  • 從參照讀取時，預期會得到直接值。例如，前置字元不應為「Bearer」。
  • 如果省略，政策執行會假設值位於授權標頭中，且採用標準格式「Bearer xyz」。
預設 不適用
存在必要性 選用
類型 流程變數

範例：

<VerifyIAM async="false" continueOnError="false" enabled="true" name="Verify-IAM-Permissions-1">
    <DisplayName>VerifyIAM policy for flow 1</DisplayName>
    <CredentialSource>request.queryparam.token</CredentialSource>
</VerifyIAM>

錯誤參考資料

本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。詳情請參閱「政策錯誤的相關資訊」和「處理錯誤」。

執行階段錯誤

政策執行時可能會發生這些錯誤。

錯誤代碼 HTTP 狀態 原因
steps.verifyiam.CredentialSourceRefUnresolved 400 無法解析憑證來源內提供的流程變數。
steps.verifyiam.CredentialValueNotProvided 400 找不到憑證。如果未提供憑證來源參照，我們會查看預設位置，例如授權標頭。
steps.verifyiam.Forbidden 403 因權限不足、缺少存取範圍或其他相關問題，無法轉送要求。
steps.verifyiam.MiscellaneousAuthorizationConfigurationError 500 向 IAM 提出驗證要求時發生問題。API 製作者必須根據錯誤回應中的詳細資料修正這項錯誤。
steps.verifyiam.Unauthorized 401 憑證有問題，例如值無效或已過期。
steps.verifyiam.UnexpectedAuthorizationInfrastructureError 500 內部錯誤。

部署錯誤

這項政策不會傳回任何政策專屬的部署錯誤。

錯誤變數

當這項政策在執行階段觸發錯誤時，系統會設定這些變數。

變數 地點 範例
fault.name="fault_name" fault_name 是錯誤名稱，如上方「執行階段錯誤」表格所列。錯誤名稱是錯誤代碼的最後一個部分。 fault.name="Unauthorized"
verifyiam.policy_name.failed policy_name 是擲回錯誤的政策的使用者指定名稱。 verifyiam.Verify-IAMToken.failed = true