SAMLAssertion 政策

<ph type="x-smartling-placeholder"></ph> 您正在查看 Apigee Edge 文档。
转到 Apigee X 文档
信息

内容

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

验证 SAML 断言

字段名称 说明
name 特性
政策实例的名称。该名称在组织中必须是唯一的。您可以在名称中使用的字符仅限于:A-Z0-9._\-$ %。 但是,管理界面会强制实施其他限制,例如 移除非字母数字字符。
ignoreContentType 个属性 可以设置为 truefalse 的布尔值。默认情况下,如果消息的内容类型不是 XML Content-Type,则不会生成断言。如果将其设置为 true,则无论内容类型如何,该消息都被视为 XML。
Source 政策的目标。有效值为 messagerequestresponse。设置为 message 时,该政策会根据其附加点有条件地检索消息对象。附加到请求流后,该政策会将 message 解析为请求,而在附加到响应流时,该政策会将 message 解析为响应。
XPath
已弃用Source 的子级。 使用 AssertionXPathSignedElementXPath
AssertionXPath
Source 的子级。XPath 表达式,指示政策可从中提取 SAML 断言的入站 XML 文档上的元素。
SignedElementXPath
Source 的子级。XPath 表达式,指示政策可从中提取经签名的元素的入站 XML 文档上的元素。这可能与 AssertionXPath 的 XPath 不同或相同。
TrustStore
TrustStore 的名称,包含用于验证 SAML 断言的数字签名的可信 X.509 证书。
RemoveAssertion
可以设置为 truefalse 的布尔值。如果为 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. 此政策会检查入站邮件,以验证请求的媒体类型是否为 XML,方法是 检查内容类型是否与格式 text/(.*+)?xmlapplication/(.*+)?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>(如上所述)。 如果验证失败,则该政策会引发故障。

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

  • 断言中的数字签名有效,已由受信 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 会话索引

错误参考信息

本部分介绍返回的错误代码和错误消息 此政策触发错误时 Edge 设置的故障变量。 在开发故障规则以处理故障时,请务必了解此信息。如需了解详情,请参阅您需要了解的有关政策错误的信息处理故障

部署错误

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

错误名称 原因 修复
SourceNotConfigured 验证 SAML 断言政策的以下一个或多个元素未定义或为空:<Source><XPath><Namespaces><Namespace>
TrustStoreNotConfigured 如果 <TrustStore> 元素为空或未在 ValidateSAMLAssertion 政策中指定,则 API 代理部署将失败。需要有效的信任库。
NullKeyStoreAlias 如果子元素 <Alias> 为空或未在生成 SAML 断言政策的 <Keystore> 元素中指定,则 API 代理部署将失败。需要有效的密钥库别名。
NullKeyStore 如果子元素 <Name> 为空或未在 GenerateSAMLAssertion 政策的 <Keystore> 元素中指定,则 API 代理部署将失败。需要有效的密钥库名称。
NullIssuer 如果 <Issuer> 元素为空或未在生成 SAML 断言政策中指定,则 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>

相关主题

提取变量:提取变量政策