GenerateSAMLAssertion 政策

可擴充的政策

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

查看 Apigee Edge 說明文件。

API Proxy 可透過 GenerateSAMLAssertion 政策，將 SAML 聲明附加至外送 XML 要求。後端服務隨後就能使用這些判斷結果，進一步處理驗證和授權作業，確保安全性。詳情請參閱「SAML 政策總覽」。

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

範例

<GenerateSAMLAssertion name="SAML" ignoreContentType="false">
  <CanonicalizationAlgorithm />
  <Issuer ref="reference">Issuer name</Issuer>
  <KeyStore>
    <Name ref="reference">keystorename</Name>
    <Alias ref="reference">alias</Alias>
  </KeyStore>
  <OutputVariable>
    <FlowVariable>assertion.content</FlowVariable>
    <Message 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>
      </Namespaces>
      <XPath>/soap:Envelope/soap:Header/wsse:Security</XPath>
    </Message>
  </OutputVariable>
  <SignatureAlgorithm />
  <Subject ref="reference">Subject name</Subject>
  <Template ignoreUnresolvedVariables="false">
    <!-- A lot of XML goes here, within CDATA, with {} around
         each variable -->
  </Template>
</GenerateSAMLAssertion>

元素參考資料

本節列出 GenerateSAMLAssertion 政策的元素和屬性。

適用於頂層元素的屬性

<GenerateSAMLAssertion name="SAML-A1" continueOnError="false" enabled="true" async="false">

所有政策父項元素都有下列屬性。

屬性 說明 預設 外觀狀態
名稱 政策的內部名稱。名稱只能使用以下字元： A-Z0-9._\-$ %。不過，Apigee 使用者介面會強制執行其他限制，例如自動移除非英數字元。

您可以視需要使用 <displayname></displayname> 元素，在 Apigee UI 代理項目編輯器中，以其他自然語言名稱標示政策。

 不適用 必填
已啟用 設為 true 即可強制執行政策。

設為 false 即可「關閉」這項政策。即使政策仍附加至流程，系統也不會強制執行。

 true 選用

用於產生 SAML 聲明的元素和屬性

欄位名稱 說明
ignoreContentType 屬性 可設為 true 或 false 的布林值。根據預設，如果訊息的內容類型不是 XML 內容類型，系統就不會產生判斷結果。如果設為 true，系統會將郵件視為 XML，無論 Content-type 為何。
Issuer
識別資訊提供者的專屬 ID。如果存在選填的 ref 屬性，系統會在執行階段根據指定的變數指派 Issuer 的值。如果沒有選填的 ref 屬性，系統會使用「發行者」的值。
KeyStore
包含私密金鑰的 KeyStore 名稱，以及用於以數位方式簽署 SAML 聲明的私密金鑰別名。
OutputVariable
指定要放置產生的 SAML 聲明。您可以在流程變數中儲存斷言，或插入現有訊息。
FlowVariable
指定要儲存產生的 SAML 聲明內容的流程變數名稱。 這是使用 <Message> 元素將判斷插入現有 XML 訊息的替代方法。
Message 政策目標。有效值為 message、request 和 response。如果設為 message，這項政策會根據政策的附加點，有條件地擷取訊息物件。附加至要求流程時，政策會將 message 解析為要求；附加至回應流程時，政策會將 message 解析為回應。
XPath XPath 運算式，指出要在外送 XML 文件中附加 SAML 判斷的元素。
SignatureAlgorithm SHA1 或 SHA256
Subject
SAML 判斷陳述主體的專屬 ID。如有選填的 ref 屬性，系統會在執行階段根據指定變數指派主旨值。如果沒有選填的 ref 屬性，系統會使用主旨的值。
Template
如果存在，系統就會執行這個範本來產生判斷結果，並將所有以 {} 表示的項目替換為對應的變數，然後以數位方式簽署結果。系統會按照 AssignMessage 政策規則處理範本。 請參閱 AssignMessage 政策。

使用須知

政策處理：

  1. 如果訊息不是 XML，且 ignoreContentType 未設為 true，則會引發錯誤。
  2. 如果設定 Template，請按照 AssignMessage 政策的說明處理範本。 如有任何變數遺失且未設定 ignoreUnresolvedVariables，請發出錯誤。
  3. 如果未設定 Template，請建構包含主體和簽發者參數值或參照的聲明。
  4. 使用指定金鑰簽署判斷。
  5. 在指定 XPath 的訊息中加入判斷結果。

錯誤參考資料

本節說明這項政策觸發錯誤時，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

錯誤回應範例

{
  "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>

相關主題

擷取變數：擷取變數政策