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 会话索引

错误参考信息

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Error name	Cause	Fix
SourceNotConfigured	One or more of the following elements of the ValidateSAMLAssertion policy is not defined or empty: <Source>, <XPath>, <Namespaces>, <Namespace>.
TrustStoreNotConfigured	If the <TrustStore> element is empty or not specified in the ValidateSAMLAssertion policy, then the deployment of the API proxy fails. A valid truststore is required.
NullKeyStoreAlias	If the child element <Alias> is empty or not specified in the <Keystore> element of GenerateSAMLAssertion policy, then the deployment of the API proxy fails. A valid keystore alias is required.
NullKeyStore	If the child element <Name> is empty or not specified in the <Keystore> element of GenerateSAMLAssertion policy, then the deployment of the API proxy fails. A valid keystore name is required.
NullIssuer	If the <Issuer> element is empty or not specified in the GenerateSAMLAssertion policy, then the deployment of the API proxy fails. A valid <Issuer> value is required.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault. The fault name is the last part of the fault code.	fault.name = "InvalidMediaTpe"
GenerateSAMLAssertion.failed	For a validate SAML assertion policy configuration, the error prefix is ValidateSAMLAssertion.	GenerateSAMLAssertion.failed = true

Example error response

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{
  "fault": {
    "faultstring": "GenerateSAMLAssertion[GenSAMLAssert]: Invalid media type",
    "detail": {
      "errorcode": "steps.saml.generate.InvalidMediaTpe"
    }
  }
}

Example fault rule

<FaultRules>
    <FaultRule name="invalid_saml_rule">
        <Step>
            <Name>invalid-saml</Name>
        </Step>
        <Condition>(GenerateSAMLAssertion.failed = "true")</Condition>
    </FaultRule>
</FaultRules>

相关主题

提取变量：提取变量政策