您正在查看 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 項屬性 |
可設為 true 或 false 的布林值。根據預設,如果訊息的內容類型不是 XML 內容類型,系統就不會產生斷言。如果設為 true ,則無論 Content-type 類型為何,系統會將訊息視為 XML。 |
||
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 屬性,系統會在執行階段根據指定的變數指派 Subject 的值。如果有選用的 ref 屬性,系統會使用 Subject 的值。
|
||
Template |
如果有,則會執行這個範本,將註明的
{} 的所有內容替換為對應的變數,然後以數位方式簽署結果,藉此產生斷言。系統會依 AssignMessage 政策規則處理範本。
請參閱「指派訊息政策」。
|
驗證 SAML 宣告
欄位名稱 | 說明 |
---|---|
name 項屬性 |
政策執行個體的名稱。名稱在機構中不得重複。
名稱中使用的字元僅限
A-Z0-9._\-$ % 個字元。不過,管理 UI 會強制執行其他限制,例如自動移除非英數字元。 |
ignoreContentType 項屬性 |
可設為 true 或 false 的布林值。根據預設,如果訊息的內容類型不是 XML 內容類型,系統就不會產生斷言。如果設為 true ,則無論 Content-type 類型為何,系統會將訊息視為 XML。 |
Source |
政策的目標。有效值為 message 、request 和 response 。設為 message 時,政策會根據政策的連結點,有條件地擷取訊息物件。附加至要求流程時,政策會解析 message 以提出要求,附加至回應流程時,政策會解析 message 以回應。 |
XPath |
已淘汰。
Source 的子項。請使用 AssertionXPath 和 SignedElementXPath 。 |
AssertionXPath |
Source 的子項。XPath 運算式,指出傳入 XML 文件中的元素,政策可以從該文件擷取 SAML 宣告。 |
SignedElementXPath |
Source 的子項。XPath 運算式,指出傳入 XML 文件中的元素,政策可以從該文件擷取已簽署的元素。這可能與 AssertionXPath 的 XPath 不同或相同。 |
TrustStore |
TrustStore 名稱包含信任的 X.509 憑證,用於驗證 SAML 宣告中的數位簽名。
|
RemoveAssertion |
可設為
true 或 false 的布林值。如果設為 true ,系統會先從要求訊息中移除 SAML 宣告,再將訊息轉送至後端服務。 |
使用須知
安全宣告標記語言 (SAML) 規格會定義各種格式和通訊協定,讓應用程式能夠交換 XML 格式資訊,以便進行驗證及授權。
「安全性宣告」是一種信任的權杖,用來描述應用程式、應用程式使用者或其他交易中的屬性。安全性斷言是由兩種實體類型管理及使用:
- 識別資訊提供者:代表參與者產生安全性宣告
- 服務供應商:透過與識別資訊提供者存在的受信任關係,驗證安全性宣告
API 平台可做為識別資訊提供者和服務供應商。這項服務可做為識別資訊提供者,產生斷言並附加至要求訊息,讓後端服務處理這些斷言。伺服器會驗證傳入要求訊息中的斷言,藉此做為服務供應商。
SAML 政策類型支援 SAML 宣告,且該宣告符合 SAML 核心規格 2.0 版,以及 WS-Security SAML 權杖設定檔規格 1.0 版。
產生 SAML 宣告
政策處理:
- 如果訊息不是 XML,且 IgnoreContentType 未設為
true
,請發出錯誤。 - 如果已設定「範本」,請按照 AssignMessage 政策的說明處理範本。 如果缺少任何變數,且未設定 IgnoreUnresolvedVariables,則會發出錯誤。
- 如未設定「範本」,請建構斷言,其中包含「主旨」和「核發者」參數的值或其參照。
- 使用指定的金鑰簽署宣告。
- 將斷言新增至指定的 XPath 的訊息中。
驗證 SAML 宣告
政策處理:
- 政策會檢查傳入訊息,確認要求的媒體類型是否與
text/(.*+)?xml
或application/(.*+)?xml
格式相符,藉此確認要求的媒體類型是否為 XML。如果媒體類型不是 XML,且未設定<IgnoreContentType>
,這項政策就會引發錯誤。 - 這項政策會剖析 XML。如果剖析失敗,就會引發錯誤。
- 這項政策會使用個別指定的 XPath (
<SignedElementXPath>
和<AssertionXPath>
) 擷取已簽署的元素和宣告。如果這些路徑沒有傳回元素,政策就會發出錯誤。 - 政策會驗證宣告是否與已簽署的元素相同,或為已簽署元素的子項。如果並非 True,政策就會發出錯誤。
- 如果宣告中包含
<NotBefore>
或<NotOnOrAfter>
元素,政策會依據 SAML Core 第 2.5.1 節所述,根據這些值檢查目前的時間戳記。 - 這項政策會套用任何其他規則來處理「條件」,如 SAML Core 第 2.5.1.1 節所述。
- 這項政策會使用上述的
<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> 。
|
build |
TrustStoreNotConfigured |
如果 <TrustStore> 元素為空白或未在 ValidationSAMLAssertion 政策中指定,代表 API Proxy 部署失敗。
必須提供有效的 Trust Store。
|
build |
NullKeyStoreAlias |
如果在 Generate SAML 斷言政策的 <Keystore> 元素中,含有空白或 <Alias> 的子元素,API Proxy 的部署作業就會失敗。必須提供有效的 KeyStore 別名。
|
build |
NullKeyStore |
如果 <Name> 的子元素 <Name> 為空白,或是未在 GenerateSAMLAssertion 政策的 <Keystore> 元素中指定,代表 API Proxy 部署失敗。必須提供有效的 KeyStore 名稱。 |
build |
NullIssuer |
如果 <Issuer> 元素為空白,或是未在 Generate SAML 斷言政策中指定,則表示 API Proxy 部署失敗。必須提供有效的 <Issuer> 值。 |
build |
錯誤變數
這些變數是在執行階段錯誤發生時設定。詳情請參閱「政策錯誤的注意事項」。
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>
相關主題
擷取變數:擷取變數政策