何时使用传递或筛选声明规则When to Use a Pass Through or Filter Claim Rule

( ) 如果需要采用特定的传入声明类型,则可以在 Active Directory 联合身份验证服务 AD FS 中使用此规则,然后应用一项操作,该操作将根据传入声明中的值确定应发生的输出。You can use this rule in Active Directory Federation Services (AD FS) when you need to take a specific incoming claim type and then apply an action that will determine what output should occur based on the values in the incoming claim. 使用此规则时,将根据你在此规则中配置的任一选项传递或筛选与下表中的规则逻辑匹配的任何声明。When you use this rule, you pass through or filter any claims that match the rule logic in the following table, based on either of the options you configure in the rule.

规则选项Rule option 规则逻辑Rule logic
传递所有声明值Pass through all claim values 如果传入声明类型等于指定的声明类型 并且值等于任意值,则传递该声明If incoming claim type equals specified claim type and value equals any value, then pass the claim through
仅传递特定的声明值Pass through only a specific claim value 如果传入声明类型等于指定的声明类型 并且值等于指定的声明值,则传递该声明If incoming claim type equals specified claim type and value equals specified claim value, then pass the claim through
仅传递与特定电子 - 邮件后缀值匹配的声明值Pass through only claim values that match a specific e-mail suffix value 如果传入声明类型等于指定的声明类型 并且值等于指定的后缀值,则传递该声明If incoming claim type equals specified claim type and value equals specified suffix value, then pass the claim through
仅传递以特定值开头的声明值Pass through only claim values that start with a specific value 如果传入声明类型等于指定的声明类型 并且值以指定的声明值 开头,则传递该声明If incoming claim type equals specified claim type and value begins with specified claim value, then pass the claim through

以下部分提供了声明规则的基本介绍,并提供了有关何时使用此规则的更多详细信息。The following sections provide a basic introduction to claim rules and provide further details about when to use this rule.

关于声明规则About claim rules

声明规则表示将接受传入声明的业务逻辑实例,如果 x 之后为 y,则对其应用条件, ( ) 并基于条件参数生成传出声明。A claim rule represents an instance of business logic that will take an incoming claim, apply a condition to it (if x then y) and produce an outgoing claim based on the condition parameters. 下面的列表概述了在进一步阅读本主题中的内容之前应了解的有关声明规则的重要提示:The following list outlines important tips that you should know about claim rules before you read further in this topic:

  • 在 AD FS 管理 "管理单元 - 中,只能使用声明规则模板创建声明规则In the AD FS Management snap-in, claim rules can only be created using claim rule templates

  • 声明规则直接从声明提供程序 ( (例如 Active Directory 或另一个联合身份验证服务)或在 ) 声明提供方信任的接受转换规则的输出中处理传入声明。Claim rules process incoming claims either directly from a claims provider (such as Active Directory or another Federation Service) or from the output of the acceptance transform rules on a claims provider trust.

  • 声明规则由声明颁发引擎按给定规则集内的时间顺序处理。Claim rules are processed by the claims issuance engine in chronological order within a given rule set. 通过为规则设置优先级,可以进一步优化或筛选由给定规则集内以前的规则生成的声明。By setting precedence on rules, you can further refine or filter claims that are generated by previous rules within a given rule set.

  • 声明规则模板始终要求你指定传入声明类型。Claim rule templates will always require you to specify an incoming claim type. 但是,你可以使用单个规则处理声明类型相同的多个声明值。However, you can process multiple claim values with the same claim type using a single rule.

有关声明规则和声明规则集的更多详细信息,请参阅声明规则的角色For more detailed information about claim rules and claim rule sets, see The Role of Claim Rules. 有关如何处理规则的详细信息,请参阅声明引擎的角色For more information about how rules are processed, see The Role of the Claims Engine. 有关如何处理声明规则集的详细信息,请参阅声明管道的角色For more information how claim rule sets are processed, see The Role of the Claims Pipeline.

传递所有声明值Pass through all claim values

使用此操作时,将指定声明类型的所有传入声明值作为传出声明传递。When using this action, all incoming claim values for the specified claim type are passed through as outgoing claims. 例如,当传入声明类型指定为“角色”声明类型时,将所有传入声明值逐个复制到传出声明类型为“角色”的新传出声明中。For example, when the incoming claim type is specified as the Role claim type, all incoming claim values are copied individually into new outgoing claims with the outgoing claim type of Role.

筛选声明Filtering a claim

在 AD FS 中,术语 "声明筛选" 指筛选或限制传入声明值,以便仅将特定值作为传出声明传递或发送。In AD FS, the term claims filtering means to filter or restrict incoming claim values so that only certain values are passed or sent through as outgoing claims. “传递或筛选传入声明”**** 规则模板使该功能变为可能。It is the Pass Through or Filter an Incoming Claim rule template that makes this function possible. 在此规则的属性内,你可以设置传入值筛选条件,以便仅传递满足指定条件的值。Within the properties of this rule, you can set conditions to filter incoming values so that only the values that meet your specified criteria are passed through.

例如,如果传入声明类型与“角色”声明类型匹配,或者你可能只想发出有关用户姓名的声明,而不发出包含用户身份证号的声明,则可以使用此规则仅传递与声明值“Purchaser”匹配的声明。For example, you can use this rule to only pass through claims that match the claim value of Purchaser when the incoming claim type matches the claim type of Role or you might want to issue only claims about the name of the user, but not claims containing the social security number of the user.

如果将某个筛选条件与此规则结合使用,将检查所有传入声明,以确定与该规则所设条件匹配的声明。When you use a filter condition with this rule, all incoming claims are examined to determine which claims match the criteria set by the rule. 忽略其他所有声明,以便仅传递与所选声明类型匹配的指定声明值。All other claims are ignored so that only specified claim values that match a selected claim type will pass through.

例如,如下图所示,如果将规则设置为仅筛选键控为 UPN 声明类型并以结尾的传入声明,则将 @fabrikam.com 忽略所有其他传入声明,除非它们满足此条件。For example, as shown in the following illustration, when a rule is set with the condition to filter only incoming claims that are keyed to the UPN claim type and also end with @fabrikam.com, all other incoming claims are ignored unless they meet this criteria. 这包括具有电子邮件地址的声明类型的传入声明, - 即使其声明值以结束 @fabrikam.com 。This includes the incoming claim with the claim type of E-Mail Address even though its claim value ends in @fabrikam.com. 在这种情况下,仅向信赖方发送包含值的声明 Nick@fabrikam.com 。In this case, only the claim containing the value of Nick@fabrikam.com is sent to the relying party.

何时使用 pass

对声明提供程序信任配置此规则Configuring this rule on a claims provider trust

使用声明提供程序信任时,可以将此规则配置为仅传递来自与特定约束匹配的声明提供程序的传入声明。When you use a claims provider trust, this rule can be configured to pass through only incoming claims from the claims provider that match certain constraints. 例如,你可能只想接受 - 来自声明提供程序的电子邮件声明; 因此,你将使用此规则模板接受 - 以声明提供程序的域名系统 DNS 名称结尾的电子邮件声明类型 ( ) 。For example, you might want to only accept e-mail claims from the claims provider; therefore, you would use this rule template to accept e-mail claim types that end in the claims provider's Domain Name System (DNS) name.

对信赖方信任配置此规则Configuring this rule on a relying party trust

使用信赖方信任时,可以将此规则配置为传递或筛选将发送给信赖方的传出声明。When you use a relying party trust, this rule can be configured to pass through or filter outgoing claims that will be sent to the relying party. 某些信赖方可能不了解某些声明类型,或者某些声明可能包含不应发送给某些信赖方的敏感信息。Some relying parties might not understand certain claim types, or certain claims might contain sensitive information that should not be sent to certain relying parties. 此规则模板可帮助为特定的信赖方信任强制实施这些策略。This rule template can help to enforce those policies for a particular relying party trust.

如何创建此规则How to create this rule

您可以使用声明规则语言或使用 "AD FS 管理" 管理单元中的 "传递或筛选传入声明规则" 模板来创建此规则 - 。You create this rule using either the claim rule language or using the Pass Through or Filter an Incoming Claim rule template in the AD FS Management snap-in. 此规则模板提供以下配置选项:This rule template provides the following configuration options:

  • 指定声明规则名称Specify a claim rule name

  • 指定传入声明类型Specify a incoming claim type

  • 传递所有声明值Pass through all claim values

  • 仅传递特定的声明值Pass through only a specific claim value

  • 仅传递与特定电子 - 邮件后缀值匹配的声明值Pass through only claim values that match a specific e-mail suffix value

  • 仅传递以特定值开头的声明值Pass through only claim values that start with a specific value

有关如何创建此模板的详细说明,请参阅 AD FS 部署指南中的创建用于传递或筛选传入声明的规则For more instructions on how to create this template, see Create a Rule to Pass Through or Filter an Incoming Claim in the AD FS Deployment Guide.

使用声明规则语言Using the claim rule language

如果仅在声明值与自定义模式匹配时才发送声明,则必须使用自定义规则。If a claim should be sent only when the claim value matches a custom pattern, you must use a custom rule. 有关详细信息,请参阅“何时使用自定义规则”。For more information, see When to Use a Custom Rule.

有关如何构造传递或筛选规则语法的示例Examples of how to construct a pass through or filter rule syntax

简单的筛选规则就是基于上述属性之一筛选声明。A simple filtering rule would filter claims based on one of the properties outlined above. 例如,下面的规则将传递所有电子 - 邮件声明:For example, the following rule will pass through all e-mail claims:

c:[type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"]  => issue(claim  = c);

筛选器可以在逻辑上与 - ed 在一起。Filters can be logically AND-ed together. 例如,下面的规则将接受 - 值为的所有电子邮件声明johndoe@fabrikam.com:For example, the following rule will accept all e-mail claims with value johndoe@fabrikam.com:

c:[type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress", value == "johndoe@fabrikam.com "]  => issue(claim  = c);

在上述示例中,筛选器始终使用相等运算符。In the above examples the filters always used an equality operator. 声明规则语言支持下列运算符:The claim rule language supports the following operators:

  • ==-等于区分 ( 大小写 -)== - equals (case-sensitive)

  • !=-不等于 ( 区分大小写 -)!= - not equals (case-sensitive)

  • =~-正则表达式匹配=~- regular expression match

  • !~ -正则表达式不 - 匹配!~ - regular expression non-match

例如,下面的规则将接受 - 后缀为 boeing.com 的本地联合服务器未颁发的所有电子邮件声明:For example, the following rule will accept all e-mail claims not issued by the local federation server that have a suffix of boeing.com:

c:[type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress", value =~ "^.*@boeing\.com$" , issuer != "LOCAL AUTHORITY"]  => issue(claim  = c);

创建自定义规则的最佳做法Best practices for creating custom rules

可以向每个声明的一个或多个属性应用筛选器,如下表所述。A filter can be applied to one or more of the properties of each claim, as described in the following table.

声明属性Claim property 描述Description
类型Type (通常表示为 Uri 的声明类型 ) 反映了联合中合作伙伴在声明中传达的信息类型的隐式协议。The claim type (usually represented as an Uri) reflects an implicit agreement between partners in a Federation about what kind of information is conveyed in the claim. 例如,http: / /schemas.xmlsoap.org / ws / 2005 / 05 / identity 声明 emailaddress 类型的 / 声明 / 将包含用户的电子 - 邮件地址。For example, claims of type http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress will contain the e-mail address of the user.
“值”Value 声明的值。The value of the claim. 例如,http: / /schemas.xmlsoap.org / ws / 2005 / 05 / 标识声明 emailaddress 类型的声明 / / 可能具有值johndoe@fabrikam.comFor example, a claim of type http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress may have a value of johndoe@fabrikam.com
ValueTypeValueType ValueType 表示如何解释声明值中包含的信息。The ValueType represents how the information contained in the claim's Value is to be interpreted. 通常,ValueType 将设置为 http: / / Www.w3.org / 2001 / XMLSchema # 字符串,但声明值可能包含 Base64Binary 编码数据, ( 例如,图像 ) 或日期、布尔值等等。Typically the ValueType will be set to http://www.w3.org/2001/XMLSchema#string, but the claim value could contain Base64Binary encoded data (for example, an image) or a date, Boolean, and so on.
颁发者Issuer 发出方表示上一次发出有关用户的声明的参与方。The issuer represents the party that last issued the claims about the user. 如果声明是在声明提供程序联合服务器中获取的,则所有声明的颁发者都将设置为 "本地颁发机构"。If the claims are obtained at a claims provider federation server the issuer of all claims is going to be set to "LOCAL AUTHORITY". 如果声明由联合提供程序联合服务器接收,则声明的发出方将设置为已对令牌签名的声明提供程序的声明提供程序标识符。If the claims were received by a Federation Provider federation server, the issuer of the claims is going to be set to the claims provider identifier of the claims provider that signed the token. 因此,当处理从声明提供程序收到的声明上的规则时,所有声明的发出方都将设置为相同的值。Thus, when processing rules on claims received from a claims provider the issuer of all claims is going to be set to the same value. 为信赖方创作规则时,可使用 issuer 属性来区分来自不同声明提供程序的声明。When authoring rules for a relying party, the issuer property can be used to distinguish between claims originating from different claims providers.
OriginalIssuerOriginalIssuer 此声明属性旨在说明最初发出声明的联合服务器。This claim property is meant to convey which federation server originally issued the claim. 由于声明的 issuer 属性设置为对令牌签名的最后一台联合服务器,因此,在声明已流经多台联合服务器的情况下,原始颁发者非常有用, ( 例如,从联合提供程序联合服务器接收令牌的信赖方可能会对哪个特定声明提供程序联合服务器对用户进行身份验证感兴趣)Since the issuer property of claims is set to the last federation server that signed the token, the original issuer is useful in scenarios where a claim has flowed through more than one federation server (For example, a relying party that receives a token from a federation provider federation server might be interested which particular claims provider federation server authenticated the user)
属性Properties 除上述五种属性外,每个声明还有一个可以存储命名属性的属性包。In addition to the five properties outlined above, each claim also has a property bag where named properties can be stored. 这些属性在令牌中不会序列化,只能用于在单台联合服务器范围内的声明发出管道的组件之间传递信息。These properties are not serialized in the token and only make sense for passing information between components of the claims issuance pipeline within the scope of a single federation server. 例如,在声明提供程序规则处理然后在信赖方规则中引用属性的过程中设置该属性。For example, setting a property during claims provider rules processing and then referring to it in relying party rules.