Udostępnij za pośrednictwem

When to Use a Pass Through or Filter Claim Rule

  • Artykuł

 

Applies To: Windows Server 2012

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

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:

  • In the AD FS Management snap-in, claim rules can only be created using claim rule templates

  • 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

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.

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.

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. This includes the incoming claim with the claim type of E-Mail Address even though its claim value ends in @fabrikam.com. In this case, only the claim containing the value of Nick@fabrikam.com is sent to the relying party.

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

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

For more instructions on how to create this template, see Create a Rule to Pass Through or Filter an Incoming Claim1 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 == “https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress”]  => issue(claim  = c);

Filters can be logically AND-ed together. For example, the following rule will accept all e-mail claims with value johndoe@fabrikam.com:

c:[type == “https://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

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 == “https://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

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. For example, claims of type https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress will contain the e-mail address of the user.

Value

The value of the claim. For example, a claim of type https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress may have a value of johndoe@fabrikam.com

ValueType

The ValueType represents how the information contained in the claim’s Value is to be interpreted. Typically the ValueType will be set to https://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. When authoring rules for a relying party, the issuer property can be used to distinguish between claims originating from different claims providers.

OriginalIssuer

This claim property is meant to convey which federation server originally issued the claim. 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.