SAML 宣告政策

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件
資訊

優勢

  • 傳入驗證和授權:驗證 SAML 宣告政策
    SAML 政策類型可讓 API Proxy 驗證附加至傳入 SOAP 要求的 SAML 宣告。SAML 政策會驗證傳入的訊息,其中包含經過數位簽署的 SAML 宣告,如果訊息無效,請予以拒絕,並設定允許其他政策的變數或後端服務本身,以便進一步驗證斷言中的資訊。
  • 產生傳出權杖:產生 SAML 宣告政策
    SAML 政策類型可讓 API Proxy 將 SAML 宣告附加至傳出 XML 要求。 接著,這些斷言可讓後端服務啟用,以針對驗證和授權進行進階安全性處理。

範例

產生 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="test">http://www.example.com/test</Namespace>
      </Namespaces>
      <XPath>/envelope/header</XPath>
    </Message>
  </OutputVariable>
  <SignatureAlgorithm />
  <Subject ref="reference">Subject name</Subject>
  <Template ignoreUnresolvedVariables="false">
    <!-- A lot of XML goes here, in 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._\-$ % 個字元。不過,管理 UI 會強制執行其他限制,例如自動移除非英數字元。
ignoreContentType 項屬性 可設為 truefalse 的布林值。根據預設,如果訊息的內容類型不是 XML 內容類型,系統就不會產生斷言。如果設為 true,則無論 Content-type 類型為何,系統會將訊息視為 XML。
Issuer
識別資訊提供者的專屬 ID。如果有選用的 ref 屬性,系統會在執行階段根據指定的變數指派核發者的值。如果沒有選用的 ref 屬性,系統將使用核發者的值。
KeyStore
含有私密金鑰和私密金鑰別名的 KeyStore 名稱,可用來數位簽署 SAML 宣告。
OutputVariable
FlowVariable
Message 政策的目標。有效值為 messagerequestresponse。設為 message 時,政策會根據政策的連結點,有條件地擷取訊息物件。附加至要求流程時,政策會解析 message 以提出要求,附加至回應流程時,政策會解析 message 以回應。
XPath XPath 運算式,指出傳出 XML 文件中的元素會附加 SAML 宣告。
SignatureAlgorithm SHA1 或 SHA256
Subject
SAML 宣告主體的專屬 ID。如有選用的 ref 屬性,系統會在執行階段根據指定的變數指派 Subject 的值。如果有選用的 ref 屬性,系統會使用 Subject 的值。
Template
如果有,則會執行這個範本,將註明的 {} 的所有內容替換為對應的變數,然後以數位方式簽署結果,藉此產生斷言。系統會依 AssignMessage 政策規則處理範本。 請參閱「指派訊息政策」。

驗證 SAML 宣告

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

使用須知

安全宣告標記語言 (SAML) 規格會定義各種格式和通訊協定,讓應用程式能夠交換 XML 格式資訊,以便進行驗證及授權。

「安全性宣告」是一種信任的權杖,用來描述應用程式、應用程式使用者或其他交易中的屬性。安全性斷言是由兩種實體類型管理及使用:

  • 識別資訊提供者:代表參與者產生安全性宣告
  • 服務供應商:透過與識別資訊提供者存在的受信任關係,驗證安全性宣告

API 平台可做為識別資訊提供者和服務供應商。這項服務可做為識別資訊提供者,產生斷言並附加至要求訊息,讓後端服務處理這些斷言。伺服器會驗證傳入要求訊息中的斷言,藉此做為服務供應商。

SAML 政策類型支援 SAML 宣告,且該宣告符合 SAML 核心規格 2.0 版,以及 WS-Security SAML 權杖設定檔規格 1.0 版。

產生 SAML 宣告

政策處理:

  1. 如果訊息不是 XML,且 IgnoreContentType 未設為 true,請發出錯誤。
  2. 如果已設定「範本」,請按照 AssignMessage 政策的說明處理範本。 如果缺少任何變數,且未設定 IgnoreUnresolvedVariables,則會發出錯誤。
  3. 如未設定「範本」,請建構斷言,其中包含「主旨」和「核發者」參數的值或其參照。
  4. 使用指定的金鑰簽署宣告。
  5. 將斷言新增至指定的 XPath 的訊息中。

驗證 SAML 宣告

政策處理:

  1. 政策會檢查傳入訊息,確認要求的媒體類型是否與 text/(.*+)?xmlapplication/(.*+)?xml 格式相符,藉此確認要求的媒體類型是否為 XML。如果媒體類型不是 XML,且未設定 <IgnoreContentType>,這項政策就會引發錯誤。
  2. 這項政策會剖析 XML。如果剖析失敗,就會引發錯誤。
  3. 這項政策會使用個別指定的 XPath (<SignedElementXPath><AssertionXPath>) 擷取已簽署的元素和宣告。如果這些路徑沒有傳回元素,政策就會發出錯誤。
  4. 政策會驗證宣告是否與已簽署的元素相同,或為已簽署元素的子項。如果並非 True,政策就會發出錯誤。
  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 立即驗證驗證
saml.authnSessionIndex 驗證工作階段索引

錯誤參考資料

本節說明這項政策觸發錯誤時傳回的錯誤代碼和錯誤訊息,以及 Edge 設定的錯誤變數。如果您正在開發錯誤規則來處理錯誤,請務必瞭解這項資訊。詳情請參閱「政策錯誤須知」和「處理錯誤」。

部署錯誤

若您部署包含這項政策的 Proxy,就可能會發生這些錯誤。

錯誤名稱 原因 修正
SourceNotConfigured 下列一或多項驗證 SAML 宣告政策元素未定義或空白:<Source><XPath><Namespaces><Namespace>
TrustStoreNotConfigured 如果 <TrustStore> 元素為空白或未在 ValidationSAMLAssertion 政策中指定,代表 API Proxy 部署失敗。 必須提供有效的 Trust Store。
NullKeyStoreAlias 如果在 Generate SAML 斷言政策的 <Keystore> 元素中,含有空白或 <Alias> 的子元素,API Proxy 的部署作業就會失敗。必須提供有效的 KeyStore 別名。
NullKeyStore 如果 <Name> 的子元素 <Name> 為空白,或是未在 GenerateSAMLAssertion 政策的 <Keystore> 元素中指定,代表 API Proxy 部署失敗。必須提供有效的 KeyStore 名稱。
NullIssuer 如果 <Issuer> 元素為空白,或是未在 Generate SAML 斷言政策中指定,則表示 API Proxy 部署失敗。必須提供有效的 <Issuer> 值。

錯誤變數

這些變數是在執行階段錯誤發生時設定。詳情請參閱「政策錯誤的注意事項」。

Variables 地點 範例
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>

相關主題

擷取變數:擷取變數政策