SAML 宣告政策

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

查看 Apigee Edge 說明文件。

結果

• 傳入驗證和授權：驗證 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，這項政策會根據政策的附加點，有條件地擷取訊息物件。附加至要求 Flow 時，這項政策會將 message 解析為要求；附加至回應 Flow 時，這項政策會將 message 解析為回應。
XPath	XPath 運算式，指出要在外送 XML 文件中附加 SAML 判斷的元素。
SignatureAlgorithm	SHA1 或 SHA256
Subject	SAML 判斷主體的專屬 ID。如有選用的 ref 屬性，系統會在執行階段根據指定變數指派主旨值。如有選用的 ref 屬性，系統會使用主旨的值。
Template	如果存在，系統就會執行這個範本來產生判斷結果，並將所有以 {} 表示的項目替換為對應的變數，然後以數位方式簽署結果。系統會按照 AssignMessage 政策規則處理範本。 請參閱 AssignMessage 政策。 <Template> 元素支援稱為訊息範本的動態字串替代功能。只有在政策簽章為 GenerateSamlAssertion 時，才支援訊息範本。

驗證 SAML 聲明

欄位名稱	說明
name 屬性	政策執行個體的名稱。機構中的名稱不得重複。 名稱只能使用以下字元：A-Z0-9._\-$ %。 不過，Apigee UI 會強制執行其他限制，例如自動移除非英數字元。
ignoreContentType 屬性	可設為 true 或 false 的布林值。根據預設，如果郵件的內容類型不是 XML 內容類型，系統就不會產生判斷結果。如果設為 true，系統會將郵件視為 XML，無論 Content-type 為何。
Source	政策目標。有效值為 message、request 和 response。如果設為 message，這項政策會根據政策的附加點，有條件地擷取訊息物件。附加至要求 Flow 時，這項政策會將 message 解析為 request；附加至回應 Flow 時，這項政策會將 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 工作階段索引

錯誤參考資料

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

相關主題

擷取變數：Extract Variables policy