ValidateSAMLAssertion 政策

可扩展政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

ValidateSAMLAssertion 政策可让 API 代理验证附加到入站 SOAP 请求的 SAML 断言。SAML 政策会验证包含经过数字签名的 SAML 断言的传入消息、拒绝这些消息（如果无效）并设置允许额外政策或后端服务本身的变量，从而进一步验证断言中的信息。如需了解详情，请参阅 SAML 政策概览。

此政策是一项可扩展政策，使用此政策可能会影响费用或使用情况，具体取决于您的 Apigee 许可。如需了解政策类型和使用情况影响，请参阅政策类型。

示例

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

字段名称 说明
name 特性
政策实例的名称。该名称在组织中必须是唯一的。您可以在名称中使用的字符仅限于：A-Z0-9._\-$ %。 但是，Apigee 界面会强制执行其他限制，例如自动移除非字母数字字符。
ignoreContentType 特性 可以设置为 true 或 false 的布尔值。默认情况下，如果消息的内容类型不是 XML Content-Type，则不会验证断言。如果将其设置为 true，则无论内容类型如何，该消息都被视为 XML。
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 断言。

使用说明

政策处理：

  1. 该政策通过检查内容类型是否匹配 text/(.*+)?xml 格式或 application/(.*+)?xml 格式来验证请求的入站媒体类型是否为 XML。如果媒体类型不是 XML 且 ignoreContentType 属性未设置为 true，则该政策会引发故障。
  2. 该政策将解析 XML。如果解析失败，则会引发故障。
  3. 该政策将使用指定的相应 XPath（<SignedElementXPath> 和 <AssertionXPath>）提取经签名的元素和断言。如果其中任何一个路径未返回元素，则政策将引发故障。
  4. 该政策将验证该断言与经签名的元素是否相同，或者该断言是否为经签名的元素的子元素。如果情况不属实，该政策将引发故障。
  5. 如果该断言中存在 <NotBefore> 或 <NotOnOrAfter> 元素之一，则该政策会根据这些值检查当前时间戳，具体如 SAML Core 第 2.5.1 节中所述。
  6. 该政策会应用任何其他规则来处理“条件”，具体如 SAML Core 第 2.5.1.1 节中所述。
  7. 该政策使用上述受信任证书存储区值 (<TrustStore>) 验证 XML 数字签名。如果验证失败，该政策会引发故障。

一旦政策已完成且不会引发故障，代理的开发者就可以确信以下几点：

  • 断言中的数字签名有效，已由受信 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 设置的故障变量。在开发故障规则以处理故障时，请务必了解此信息。如需了解详情，请参阅您需要了解的有关政策错误的信息和处理故障。

部署错误

在您部署包含此政策的代理时，可能会发生这些错误。

错误名称 原因 修复
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

错误响应示例

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

相关主题

提取变量：提取变量政策