ValidateSAMLAssertion 政策

可擴充的政策

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

API Proxy 可透過 ValidateSAMLAssertion 政策，驗證附加至傳入 SOAP 要求中的 SAML 聲明。SAML 政策會驗證含有數位簽章 SAML 聲明的傳入訊息，如果無效則會拒絕，並設定變數，讓其他政策或後端服務本身進一步驗證聲明中的資訊。詳情請參閱「SAML 政策總覽」。

這項政策是可擴充政策，使用這項政策可能會產生費用或影響用量，具體情況取決於您的 Apigee 授權。如要瞭解政策類型和使用方式的影響，請參閱「政策類型」。

範例

<ValidateSAMLAssertion name="SAML" ignoreContentType="false">
  <Source name="request">
    <Namespaces>
      <Namespace prefix='soap'>http://schemas.xmlsoap.org/soap/envelope/</Namespace>
      <Namespace prefix='wsse'>http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd</Namespace>
      <Namespace prefix='saml'>urn:oasis:names:tc:SAML:2.0:assertion</Namespace>
    </Namespaces>
    <AssertionXPath>/soap:Envelope/soap:Header/wsse:Security/saml:Assertion</AssertionXPath>
    <SignedElementXPath>/soap:Envelope/soap:Header/wsse:Security/saml:Assertion</SignedElementXPath>
  </Source>
  <TrustStore>TrustStoreName</TrustStore>
  <RemoveAssertion>false</RemoveAssertion>
</ValidateSAMLAssertion>

元素參考資料

驗證 SAML 聲明

欄位名稱	說明
`name` 屬性	政策執行個體的名稱。機構中的名稱不得重複。名稱只能使用以下字元：`A-Z0-9._\-$ %`。不過，Apigee UI 會強制執行其他限制，例如自動移除非英數字元。
`ignoreContentType` 屬性	可設為 `true` 或 `false` 的布林值。根據預設，如果郵件的內容類型不是 XML 內容類型，系統就不會驗證判斷結果。如果設為 `true`，系統會將郵件視為 XML，無論 Content-type 為何。
`Source`	政策目標。有效值為 `message`、`request` 和 `response`。如果設為 `message`，這項政策會根據政策的附加點，有條件地擷取訊息物件。附加至要求流程時，政策會將 `message` 解析為 `request`；附加至回應流程時，政策會將 `message` 解析為 `response`。
`XPath`	已淘汰。「`Source`」的子項。這時請使用 `AssertionXPath` 和 `SignedElementXPath`。
`AssertionXPath`	「`Source`」的子項。XPath 運算式，指出政策可從中擷取 SAML 判斷的輸入 XML 文件元素。
`SignedElementXPath`	「`Source`」的子項。XPath 運算式，指出政策可從中擷取簽署元素的傳入 XML 文件元素。這可能與 `AssertionXPath` 的 XPath 相同或不同。
`TrustStore`	TrustStore 的名稱，其中包含用於驗證 SAML 判斷中數位簽章的受信任 X.509 憑證。
`RemoveAssertion`	可設為 `true` 或 `false` 的布林值。當 `true`時，系統會先從要求訊息中移除 SAML 判斷提示，再將訊息轉送至後端服務。

使用須知

政策處理：

這項政策會檢查傳入的訊息，確認要求的媒體類型為 XML，方法是檢查內容類型是否符合 text/(.*+)?xml 或 application/(.*+)?xml 格式。如果媒體類型不是 XML，且 ignoreContentType 屬性未設為 true，政策就會引發錯誤。
這項政策會剖析 XML。如果剖析失敗，系統會引發錯誤。
這項政策會使用指定的 XPath (<SignedElementXPath> 和 <AssertionXPath>) 擷取已簽署的元素和判斷結果。如果其中一個路徑未傳回元素，這項政策就會引發錯誤。
這項政策會驗證聲明是否與已簽署的元素相同，或是已簽署元素的子項。如果不是，政策就會觸發錯誤。
如果斷言中存在 <NotBefore> 或 <NotOnOrAfter> 元素，政策會根據這些值檢查目前的時間戳記，如 SAML Core 2.5.1 節所述。
這項政策會套用處理「條件」的任何額外規則，如 SAML Core 第 2.5.1.1 節所述。
這項政策會使用上述信任存放區值 (<TrustStore>) 驗證 XML 數位簽章。如果驗證失敗，政策就會觸發錯誤訊息。

如果政策順利完成且未引發錯誤，Proxy 開發人員可以確定下列事項：

聲明中的數位簽章有效，且由可信任的 CA 簽署
斷言在目前時間範圍內有效
系統會擷取判斷結果的主體和簽發者，並在流程變數中設定。其他政策有責任使用這些值進行額外驗證，例如檢查主體名稱是否有效，或將其傳遞至目標系統進行驗證。

您可以使用其他政策 (例如 ExtractVariables) 剖析聲明的原始 XML，進行更複雜的驗證。

流程變數

SAML 聲明中可指定許多資訊。SAML 聲明本身是 XML，可使用 ExtractVariables 政策和其他機制進行剖析，以便實作更複雜的驗證。

變數	說明
`saml.id`	SAML 聲明 ID
`saml.issuer`	判斷的「簽發者」，從原生 XML 型別轉換為字串
`saml.subject`	判斷結果的「主體」，從原生 XML 型別轉換為字串
`saml.valid`	根據有效性檢查結果傳回 true 或 false
`saml.issueInstant`	IssueInstant
`saml.subjectFormat`	主旨格式
`saml.scmethod`	主體確認方式
`saml.scdaddress`	主體確認資料地址
`saml.scdinresponse`	回覆中的主體確認資料
`saml.scdrcpt`	主體驗證資料收件者
`saml.authnSnooa`	AuthnStatement SessionNotOnOrAfter
`saml.authnContextClassRef`	AuthnStatement AuthnContextClassRef
`saml.authnInstant`	AuthnStatement AuthInstant
`saml.authnSessionIndex`	AuthnStatement 工作階段索引

錯誤參考資料

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

部署錯誤

部署含有這項政策的 Proxy 時，可能會發生這些錯誤。

錯誤名稱	原因	修正
`SourceNotConfigured`	`ValidateSAMLAssertion` 政策中未定義或為空白的 `<Source>`、`<XPath>`、`<Namespaces>` 和 `<Namespace>` 等一或多個元素。
`TrustStoreNotConfigured`	如果 `<TrustStore>` 元素為空白，或是未在 `ValidateSAMLAssertion` 政策中指定，則 API 代理程式部署作業會失敗。必須提供有效的信任存放區。
`NullKeyStoreAlias`	如果子元素 `<Alias>` 為空白，或是未在 `GenerateSAMLAssertion` 政策的 `<Keystore>` 元素中指定，則 API 代理程式會部署失敗。必須提供有效的鍵庫別名。
`NullKeyStore`	如果子元素 `<Name>` 為空白，或是未在 `GenerateSAMLAssertion` 政策的 `<Keystore>` 元素中指定，則 API 代理程式會部署失敗。請提供有效的鍵值庫名稱。
`NullIssuer`	如果 `<Issuer>` 元素為空白，或是未在 `GenerateSAMLAssertion` 政策中指定，則 API 代理程式部署作業會失敗。必須提供有效的 `<Issuer>` 值。

錯誤變數

這些變數會在發生執行階段錯誤時設定。詳情請參閱「關於政策錯誤的相關資訊」。

變數	地點	範例
`fault.name="fault_name"`	`fault_name` 是錯誤的名稱。錯誤名稱是錯誤代碼的最後一個部分。	`fault.name = "InvalidMediaTpe"`
`GenerateSAMLAssertion.failed`	如果是有效的 SAML 斷言政策設定，錯誤前置字會是 `ValidateSAMLAssertion`。	`GenerateSAMLAssertion.failed = true`

錯誤回應範例

注意：如要處理錯誤，最佳做法是擷取錯誤回應的 errorcode 部分。請勿依賴 faultstring 中的文字，因為該文字可能會變更。

{
  "fault": {
    "faultstring": "GenerateSAMLAssertion[GenSAMLAssert]: Invalid media type",
    "detail": {
      "errorcode": "steps.saml.generate.InvalidMediaTpe"
    }
  }
}

錯誤規則範例

<FaultRules>
    <FaultRule name="invalid_saml_rule">
        <Step>
            <Name>invalid-saml</Name>
        </Step>
        <Condition>(GenerateSAMLAssertion.failed = "true")</Condition>
    </FaultRule>
</FaultRules>

ValidateSAMLAssertion 政策 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

範例

元素參考資料

驗證 SAML 聲明

使用須知

流程變數

錯誤參考資料

部署錯誤

錯誤變數

錯誤回應範例

錯誤規則範例

相關主題

ValidateSAMLAssertion 政策