When to Use a Pass Through or Filter Claim Rule

Applies To: Active Directory Federation Services (AD FS) 2.0

You can use this rule in Active Directory Federation Services (AD FS) 2.0 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.

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 2.0 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 2.0, 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 2.0 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 Claim in the AD FS 2.0 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.