When to Use a Custom Claim Rule

You write a custom claim rule in Active Directory Federation Services (AD FS) using the claim rule language, which is the framework that the claims issuance engine uses to programmatically generate, transform, pass through, and filter claims. By using a custom rule, you can create rules with more complex logic than a standard rule template. Consider using a custom rule when you want to:

  • Send claims based on values that are extracted from a Structured Query Language (SQL) attribute store.

  • Send claims based on values that are extracted from a Lightweight Directory Access Protocol (LDAP) attribute store using a custom LDAP filter.

  • Send claims based on values that are extracted from a custom attribute store.

  • Send claims only when two or more incoming claims are present.

  • Send claims only when an incoming claim value matches a complex pattern.

  • Send claims with complex changes to an incoming claim value.

  • Create claims for use only in later rules, without actually sending the claims.

  • Construct an outgoing claim from the content of more than one incoming claim.

You can also use a custom rule when the claim value of the outgoing claim must be based on the value of the incoming claim, but it must also include additional content.

The claims rule language is rule based. It has a condition part and an execution part. You can use the claim rule language syntax to enumerate, add, delete, or modify claims to meet the needs of your organization. For more information about how each of these parts works, see The Role of the Claim Rule Language.

The following sections provide a basic introduction to claim rules. They also provide details about when to use a custom claim rule.

About claim rules

A claim rule represents an instance of business logic that takes an incoming claim, apply a condition to it (if x, then y) and produce an outgoing claim based on the condition parameters.

Important

  • In the AD FS Management snap-in, claim rules can be created only 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 the rules, you can further refine or filter claims that are generated by previous rules within a given rule set.
  • Claim rule templates always require you to specify an incoming claim type. However, you can process multiple claim values with the same claim type by 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.

How to create this rule

You create this rule by first authoring the syntax that you need for your operation using the claim rule language and then pasting the result into the text box that is provided in the Send a Claims Using a Custom Rule template on the properties of either a claims provider trust or a relying party trust in the AD FS Management snap-in.

This rule template provides the following options:

  • Specify a claim rule name

  • Type one or more optional conditions and an issuance statement using the AD FS claim rule language

For more instructions for creating a custom rule using this template, see Create a Rule to Send Claims Using a Custom Rule in the AD FS Deployment Guide.

For a better understanding of how the claim rule language works, view the claim rule language syntax of other rules that already exist in the snap-in by clicking the View Rule Language tab in the properties for that rule. Using the information in this section and the syntax information on this tab can provide insight into how to construct your own custom rules.

For more information about how to use the claim rule language, see The Role of the Claim Rule Language.

Using the claim rule language

Example: How to combine first and last names based on a user's name attribute values

The following rule syntax combines first and last names from attribute values in a given attribute store. The policy engine forms a cartesian product of the matches for each condition. For example, the output for first name {"Frank", "Alan"} and last names {"Miller", "Shen"} is {"Frank Miller", "Frank Shen", "Alan Miller", "Alan Shen"}:

c1:[type == "http://exampleschema/firstname" ]
&&  c2:[type == "http://exampleschema/lastname",]
=> issue(type = "http://exampleschema/name", value = c1.value + "  " + c2.value);

Example: How to issue a manager claim based on whether users have direct reports

The following rule issues a manager claim only if the user has direct reports:

c:[type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"] => add(store = "SQL Store", types = ("http://schemas.xmlsoap.org/claims/Reports"), query = "SELECT Reports FROM dbo.DirectReports WHERE UserName = {0}", param = c.value );
count([type == "http://schemas.xmlsoap.org/claims/Reports"] ) > 0 => issue(= "http://schemas.xmlsoap.org/claims/ismanager", value = "true");

Example: How to issue a PPID claim based on an LDAP attribute

The following rule issues a Private Personal Identifier (PPID) claim based on the windowsaccountname and originalissuer attributes of users in an LDAP attribute store:

c:[Type == "https://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]
 => issue(store = "_OpaqueIdStore", types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier"), query = "{0};{1};{2}", param = "ppid", param = c.Value, param = c.OriginalIssuer);

Common attributes that can be used to uniquely identify the user for this query include the following:

  • user SID

  • windowsaccountname

  • samaccountname