SAML 宣告政策

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

查看 Apigee Edge 說明文件。

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

  • 傳入驗證和授權：驗證 SAML 聲明政策
    API Proxy 可透過 SAML 政策類型，驗證附加至傳入 SOAP 要求的 SAML 聲明。SAML 政策會驗證含有數位簽章 SAML 聲明的傳入訊息，如果無效則會拒絕，並設定變數，讓其他政策或後端服務本身進一步驗證聲明中的資訊。
  • 傳出權杖產生：產生 SAML 聲明政策
    API Proxy 可透過 SAML 政策類型，將 SAML 聲明附加至傳出的 XML 要求。 這些判斷結果隨即會提供給後端服務，以便套用進一步的安全處理程序，進行驗證和授權。

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

範例

產生 SAML 聲明

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

產生 SAML 聲明

驗證 SAML 判斷

<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 判斷

元素參考資料

產生 SAML 聲明

欄位名稱 說明
name 屬性 政策執行個體的名稱。機構中的名稱不得重複。名稱只能使用以下字元：A-Z0-9._\-$ %。不過，Apigee UI 會強制執行其他限制，例如自動移除非英數字元。
ignoreContentType 屬性 可設為 true 或 false 的布林值。根據預設，如果訊息的內容類型不是 XML 內容類型，系統就不會產生判斷結果。如果設為 true，系統會將郵件視為 XML，無論 Content-type 為何。
Issuer
身分識別提供者的專屬 ID。如果存在選填的 ref 屬性，系統會在執行階段根據指定的變數指派「發行者」的值。如果沒有選填的 ref 屬性，系統會使用「發行者」的值。
KeyStore
包含私密金鑰的 KeyStore 名稱，以及用於以數位方式簽署 SAML 聲明的私密金鑰別名。
OutputVariable
FlowVariable
Message 政策目標。有效值為 message、request 和 response。如果設為 message，這項政策會根據政策的附加點，有條件地擷取訊息物件。附加至要求流程時，政策會將 message 解析為要求；附加至回應流程時，政策會將 message 解析為回應。
XPath XPath 運算式，指出要在外送 XML 文件中附加 SAML 判斷的元素。
SignatureAlgorithm SHA1 或 SHA256
Subject
SAML 判斷陳述主體的專屬 ID。如有選填的 ref 屬性，系統會在執行階段根據指定變數指派主旨值。如果提供選用的 ref 屬性，系統會使用主旨值。
Template
如果存在，系統就會執行這個範本來產生判斷結果，並將所有以 {} 表示的項目替換為對應的變數，然後以數位方式簽署結果。系統會按照 AssignMessage 政策規則處理範本。 請參閱 AssignMessage 政策。

驗證 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 判斷提示，再將訊息轉送至後端服務。

使用須知

安全宣告標記語言 (SAML) 規格定義了格式和通訊協定，可讓應用程式交換 XML 格式的資訊，以進行驗證和授權。

「安全聲明」是描述應用程式、應用程式使用者或交易中其他參與者屬性的可信權杖。安全聲明由兩種類型的實體管理及使用：

  • 識別資訊提供者：代表參與者產生安全聲明
  • 服務供應商：透過與身分識別提供者的信任關係，驗證安全聲明

API 平台可做為身分識別提供者和服務供應商。這個服務會產生聲明並附加至要求訊息，做為身分識別提供者，讓後端服務處理這些聲明。這個服務會驗證傳入要求訊息中的聲明，做為服務供應商。

SAML 政策類型支援符合 SAML Core 規格 2.0 版和 WS-Security SAML 權杖設定檔規格 1.0 版的 SAML 判斷。

產生 SAML 聲明

政策處理：

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

驗證 SAML 聲明

政策處理：

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

錯誤參考資料

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.

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

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

相關主題

擷取變數：擷取變數政策