GenerateSAMLAssertion 政策

可扩展政策

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

通过 GenerateSAMLAssertion 政策，API 代理可以将 SAML 断言附加到出站 XML 请求。这些断言随后可用于让后端服务应用进一步的安全处理，以进行身份验证和授权。如需了解详情，请参阅 SAML 政策概览。

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

示例

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

元素参考

本部分列出了 GenerateSAMLAssertion 政策的元素和属性。

适用于顶级元素的属性

<GenerateSAMLAssertion name="SAML-A1" continueOnError="false" enabled="true" async="false">

以下属性是所有政策的父级元素都具有的属性。

属性 说明 默认 状态
name 政策的内部名称。您可以在名称中使用的字符仅限于 A-Z0-9._\-$ %。但是，Apigee 界面会实施其他限制，例如自动移除非字母数字字符。

（可选）使用 <displayname></displayname> 元素在 Apigee 界面代理编辑器中给政策添加不同的自然语言名称标签。

 不适用 必需
已启用 设置为 true 可实施政策。

设置为 false 可“关闭”政策。即使政策仍附加到某个流，也不会实施该政策。

 true 可选

用于生成 SAML 断言的元素和属性

字段名称 说明
ignoreContentType 特性 可以设置为 true 或 false 的布尔值。默认情况下，如果消息的内容类型不是 XML Content-Type，则不会生成断言。如果将其设置为 true，则无论内容类型如何，该消息都被视为 XML。
Issuer
身份提供商的唯一标识符。如果存在可选的 ref 特性，则系统会根据指定变量在运行时分配“颁发者”的值。如果可选的 ref 特性不存在，则将使用“颁发者”的值。
KeyStore
KeyStore 的名称，包含私钥以及用于对 SAML 断言进行数字签名的私钥的别名。
OutputVariable
指定生成的 SAML 断言的放置位置。断言可以存储在流变量中，也可以插入到现有消息中。
FlowVariable
指定将存储生成的 SAML 断言内容的流变量的名称。 这是使用 <Message> 元素将断言插入现有 XML 消息的替代方法。
Message 政策的目标。有效值为 message、request 和 response。设置为 message 时，该政策会根据其附加点有条件地检索消息对象。附加到请求流后，该政策会将 message 解析为请求，而在附加到响应流时，该政策会将 message 解析为响应。
XPath XPath 表达式，指示政策将 SAML 断言附加到的出站 XML 文档上的元素。
SignatureAlgorithm SHA1 或 SHA256
Subject
SAML 断言的主题的唯一标识符。如果存在可选的 ref 特性，则系统会根据指定变量在运行时分配主题值。如果不存在可选的 ref 特性，则将使用“主题”的值。
Template
如果存在，系统将通过运行此模板生成断言，将指示 {} 的所有内容替换为对应的变量，然后对结果进行数字签名。该模板是根据 AssignMessage 政策规则进行处理的。请参阅 AssignMessage 政策。

使用说明

政策处理：

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

错误参考信息

本部分介绍当此政策触发错误时返回的故障代码和错误消息，以及由 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>

相关主题

提取变量：提取变量政策