SAMLAssertion 政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

是什么

• 入站身份验证和授权：验证 SAML 断言政策
  SAML 政策类型可让 API 代理验证附加到入站 SOAP 请求的 SAML 断言。SAML 政策会验证包含经过数字签名的 SAML 断言的传入消息、拒绝这些消息（如果无效）并设置允许额外政策或后端服务本身的变量，从而进一步验证断言中的信息。
• 出站令牌生成：生成 SAML 断言政策
  通过 SAML 政策类型，API 代理可以将 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 界面会强制执行其他限制，例如自动移除非字母数字字符。
ignoreContentType 特性	可以设置为 true 或 false 的布尔值。默认情况下，如果消息的内容类型不是 XML Content-Type，则不会生成断言。如果将其设置为 true，则无论内容类型如何，该消息都被视为 XML。
Issuer	身份提供商的唯一标识符。如果存在可选的 ref 特性，则系统会根据指定变量在运行时分配“颁发者”的值。如果可选的 ref 特性不存在，则将使用“颁发者”的值。
KeyStore	KeyStore 的名称，包含私钥以及用于对 SAML 断言进行数字签名的私钥的别名。
OutputVariable
FlowVariable
Message	政策的目标。有效值为 message、request 和 response。设置为 message 时，该政策会根据其附加点有条件地检索消息对象。附加到请求流后，该政策会将 message 解析为请求，而在附加到响应流时，该政策会将 message 解析为响应。
XPath	XPath 表达式，指示政策将 SAML 断言附加到的出站 XML 文档上的元素。
SignatureAlgorithm	SHA1 或 SHA256
Subject	SAML 断言的主题的唯一标识符。如果存在可选的 ref 特性，则系统会根据指定变量在运行时分配主题值。如果存在可选的 ref 特性，则会使用主题值。
Template	如果存在，系统将通过运行此模板生成断言，将指示 {} 的所有内容替换为对应的变量，然后对结果进行数字签名。该模板是根据 AssignMessage 政策规则进行处理的。请参阅 AssignMessage 政策。 <Template> 元素支持名为消息模板的动态字符串替换功能。仅当政策签名为 GenerateSamlAssertion 时，才支持消息模板。

验证 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 断言。

---

使用说明

安全断言标记语言 (SAML) 规范定义了格式和协议，这些内容能让应用交换 XML 格式的信息以进行身份验证和授权。

“安全断言”是可信令牌，用于描述应用的特性、应用用户或事务中的一些其他参与者。安全性声明由两种类型的实体管理和使用：

• 身份提供商：代表参与者生成安全断言
• 服务提供商：通过与身份提供商建立值得信赖的关系来验证安全断言

API 平台可以充当身份提供商以及服务提供商。充当身份提供商时，它会生成断言并将其附加到请求消息，使这些断言可供后端服务进行处理。充当服务提供商时，它会验证入站请求消息的断言。

SAML 政策类型支持与 SAML Core 规范版本 2.0 和 WS-Security SAML Token Profile 规范版本 1.0 相匹配的 SAML 断言。

生成 SAML 断言

政策处理：

1. 如果消息不是 XML，且 IgnoreContentType 未设置为 true，则会引发错误。
2. 如果设置了“模板”，请按照 AssignMessage 政策中所述处理模板。如果缺少任何变量，且未设置 IgnoreUnresolvedVariables，则会引发故障。
3. 如果未设置“模板”，则需要构建一个断言，其中应包含“主题”和“颁发者”参数的值或其引用。
4. 使用指定密钥签署断言。
5. 将断言添加到指定 XPath 中的消息。

验证 SAML 断言

政策处理：

1. 该政策通过检查内容类型是否匹配 text/(.*+)?xml 格式或 application/(.*+)?xml 格式来验证请求的入站媒体类型是否为 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 数字签名。 如果验证失败，则该政策会引发故障。

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

• 断言中的数字签名有效，已由受信 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

错误响应示例

注意：处理错误时，最佳做法是捕获错误响应的 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>

相关主题

提取变量：提取变量政策