Using Claim Rules for Issuing Claims

  • Article

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

In Active Directory Federation Services (AD FS) 2.0, the claim rules (and all the server configuration details) are stored in the AD FS configuration database. In a claims-based identity model, the function of AD FS 2.0 as a Federation Service is to issue a token that contains a set of claims. The decision regarding what claims AD FS 2.0 issues is governed by claim rules. For more information about claim rules, see The Role of Claim Rules (https://go.microsoft.com/fwlink/?LinkId=182453) in the AD FS 2.0 Design Guide.

AD FS 2.0 makes issuance decisions based on identity information that is provided to it in the form of claims and other contextual information. AD FS 2.0 uses a claims engine to operate as a rules processor by taking one set of claims as input, performing a number of transformations, and then returning a different set of claims as output.

The Federation Service manages the entire end-to-end process of flowing claims through the various stages of the claims pipeline, which also includes the processing of claim rules by the claim rule engine. The following sections provide details about the claims issuance process.

The claims pipeline process

In the initial phase of claims issuance, the claims pipeline process consults the acceptance transform rule set for a given claims provider trust to determine what claim types are accepted from a given authority, that is, from a claims provider. The claims pipeline process then consults the issuance transform rules for a given relying party trust to determine what claims should be issued for a particular relying party trust.

The two sets of rules operate in a pipeline fashion. First, the processing of the acceptance transform rule set filters and, potentially, transforms the inbound set of claims that is received as input from the claims provider to return an intermediate set of claims. Next, the intermediate set in turn serves as input to the issuance transform rules. Finally, after all the rules in the issuance transform rule set are applied, the claims pipeline process returns the output of that module as a fully processed outbound set of claims.

While the claims pipeline process facilitates the end-to-end claims issuance process, it is the claims engine that performs the actual processing of each rule within a given rule set.

For more detailed information about how the claims pipeline process works, see The Role of the Claims Pipeline (https://go.microsoft.com/fwlink/?LinkId=182447) in the AD FS 2.0 Design Guide.

The claims engine process

The claims engine processes each set of rules (for example, the acceptance transform rule set of a claims provider trust) so that an output set of claims is produced. When rules are processing, the rules are applied in the order in which they appear from top to bottom, as displayed in the Edit Claim Rules dialog box in the AD FS 2.0 snap-in. This order is important, because the output of one rule can be used as the input to the next rule. When it processes a set of rules, AD FS 2.0 maintains two sets of claims: the input claim set and the output claim set. These sets have the following initial values:

  • Input claim set: The input claim set is populated based on the claims pipeline process, as described in the previous section. For acceptance transform rules, the input claim set is initially the claims that are received from the claims provider. For issuance transform rules, the input claim set is initially b the claims that are put out by the acceptance transform rules.

  • Output claim set: The output claim set is always empty initially.

As the claims engine processes rules, claims are added to the input claim set and output claim set. When a rule does not succeed in generating a claim, no claims are added to the input claims set or output claim set. When a rule succeeds in generating one or more claims, those claims are always added to the input claim set so that they are available to subsequent rules. Depending on the rule, the claim may also be added to the output claim set for the rules.

Whether the claim is added to the output claim set or not is determined by whether the rule uses the "issue" statement (the claim goes to the input claim set and the output claim set) or the "add" statement (the claim goes only to the input claim set). The rule templates always use the "issue" statement, and they put claims into the output claim set. The ability to put a claim only in the input claim set is useful if a claim is intended to be used only by subsequent rules within the same rule set. For more information about how the issue statements and add statements work, see The Role of the Claim Rule Language (https://go.microsoft.com/fwlink/?LinkId=182448) in the AD FS 2.0 Design Guide.

For more detailed information about how the claims engine process works, see The Role of the Claims Engine (https://go.microsoft.com/fwlink/?LinkId=182449) in the AD FS 2.0 Design Guide.