<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 个属性 |
可以设置为 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 政策规则进行处理的。请参阅分配消息政策。 |
验证 SAML 断言
字段名称 | 说明 |
---|---|
name 特性 |
政策实例的名称。该名称在组织中必须是唯一的。您可以在名称中使用的字符仅限于:
A-Z0-9._\-$ % 。
但是,管理界面会强制实施其他限制,例如
移除非字母数字字符。
|
ignoreContentType 个属性 |
可以设置为 true 或 false 的布尔值。默认情况下,如果消息的内容类型不是 XML Content-Type,则不会生成断言。如果将其设置为 true ,则无论内容类型如何,该消息都被视为 XML。 |
Source |
政策的目标。有效值为 message 、request 和 response 。设置为 message 时,该政策会根据其附加点有条件地检索消息对象。附加到请求流后,该政策会将 message 解析为请求,而在附加到响应流时,该政策会将 message 解析为响应。 |
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 断言
政策处理:
- 如果消息不是 XML,且 IgnoreContentType 未设置为
true
,则会引发错误。 - 如果设置了“模板”,请按照 AssignMessage 政策中所述处理模板。如果缺少任何变量,且未设置 IgnoreUnresolvedVariables,则会引发故障。
- 如果未设置“模板”,则需要构建一个断言,其中应包含“主题”和“颁发者”参数的值或其引用。
- 使用指定密钥签署断言。
- 将断言添加到指定 XPath 中的消息。
验证 SAML 断言
政策处理:
- 此政策会检查入站邮件,以验证请求的媒体类型是否为 XML,方法是
检查内容类型是否与格式
text/(.*+)?xml
或application/(.*+)?xml
。如果媒体类型不是 XML,并且 如果未设置<IgnoreContentType>
,则此政策将会引发错误。 - 该政策将解析 XML。如果解析失败,则会引发故障。
- 此政策将使用相应的 XPath 提取已签名元素和断言
(
<SignedElementXPath>
和<AssertionXPath>
)。 如果其中任何一个路径未返回元素,则该政策将引发错误。 - 该政策将验证断言是否与已签名元素相同,或者 是带符号元素的子元素。如果情况不属实,该政策将引发故障。
- 如果
<NotBefore>
或<NotOnOrAfter>
元素是否存在,则政策会根据当前时间戳 这些值(如 SAML Core 第 2.5.1 节中所述)。 - 此政策将会应用所有其他规则来处理“条件”如描述 SAML Core 第 2.5.1.1 节。
- 此政策将使用
<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> 。 |
build |
TrustStoreNotConfigured |
如果 <TrustStore> 元素为空或未在 ValidateSAMLAssertion 政策中指定,则 API 代理部署将失败。需要有效的信任库。 |
build |
NullKeyStoreAlias |
如果子元素 <Alias> 为空或未在生成 SAML 断言政策的 <Keystore> 元素中指定,则 API 代理部署将失败。需要有效的密钥库别名。 |
build |
NullKeyStore |
如果子元素 <Name> 为空或未在 GenerateSAMLAssertion 政策的 <Keystore> 元素中指定,则 API 代理部署将失败。需要有效的密钥库名称。 |
build |
NullIssuer |
如果 <Issuer> 元素为空或未在生成 SAML 断言政策中指定,则 API 代理部署将失败。需要有效的 <Issuer> 值。 |
build |
故障变量
发生运行时错误时,系统会设置这些变量。如需了解详情,请参阅您需要了解的有关政策错误的信息。
变量 | 地点 | 示例 |
---|---|---|
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>
相关主题
提取变量:提取变量政策