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 UI 會強制執行其他限制，例如自動移除非英數字元。 視需要使用 <displayname></displayname> 元素，在 Apigee UI 代理程式編輯器中，以其他自然語言名稱標示政策。	不適用	必填
已啟用	設為 true 即可強制執行政策。 設為 false 即可「關閉」這項政策。即使政策仍附加至流程，系統也不會強制執行。	true	選用

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

欄位名稱	說明
ignoreContentType 屬性	可設為 true 或 false 的布林值。根據預設，如果訊息的內容類型不是 XML 內容類型，系統就不會產生判斷結果。如果設為 true，系統會將郵件視為 XML，無論 Content-type 為何。
Issuer	身分識別提供者的專屬 ID。如果存在選填的 ref 屬性，系統會在執行階段根據指定的變數指派「發行者」的值。如果沒有選填的 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 政策。 <Template> 元素支援動態字串替代功能，稱為訊息範本。只有在政策簽章為 GenerateSamlAssertion 時，才支援訊息範本。

使用須知

政策處理：

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

錯誤參考資料

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Error name	Cause	Fix
SourceNotConfigured	One or more of the following elements of the ValidateSAMLAssertion policy is not defined or empty: <Source>, <XPath>, <Namespaces>, <Namespace>.
TrustStoreNotConfigured	If the <TrustStore> element is empty or not specified in the ValidateSAMLAssertion policy, then the deployment of the API proxy fails. A valid truststore is required.
NullKeyStoreAlias	If the child element <Alias> is empty or not specified in the <Keystore> element of GenerateSAMLAssertion policy, then the deployment of the API proxy fails. A valid keystore alias is required.
NullKeyStore	If the child element <Name> is empty or not specified in the <Keystore> element of GenerateSAMLAssertion policy, then the deployment of the API proxy fails. A valid keystore name is required.
NullIssuer	If the <Issuer> element is empty or not specified in the GenerateSAMLAssertion policy, then the deployment of the API proxy fails. A valid <Issuer> value is required.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault. The fault name is the last part of the fault code.	fault.name = "InvalidMediaTpe"
GenerateSAMLAssertion.failed	For a validate SAML assertion policy configuration, the error prefix is ValidateSAMLAssertion.	GenerateSAMLAssertion.failed = true

Example error response

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

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

Example fault rule

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

相關主題

擷取變數：擷取變數政策