When to Use a Transform Claim Rule
You can use this rule in Active Directory Federation Services (AD FS) when you need to map an incoming claim type to an outgoing claim type and then apply an action that will determine what output should occur based on the values that originated in the incoming claim. When you use this rule, you pass through or transform claims that match the following rule logic, based on either of the options that you configure in the rule, as described in the following table.
| Rule option | Rule logic |
|---|---|
| Pass through all incoming claims | If incoming claim type equals specified claim type and value equals any value, then pass the claim through with outgoing claim type equals specified claim type |
| Replace an incoming claim value with a different outgoing claim value | If incoming claim type equals specified claim type and value equals specified claim value, then transform the claim with new outgoing claim value specified claim value and with outgoing claim type specified claim type |
| Replacing incoming e-mail suffix claims with a new e-mail suffix | If incoming claim type equals specified claim type and value equals any suffix value, then transform the claim with new outgoing claim value specified suffix value and with outgoing claim type specified claim type |
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 that are keyed to a specified incoming claim type are mapped to a specified outgoing claim type before they are sent as outgoing claims into tokens that are signed by your Federation Service.
For example, when a rule is set with the Pass through all claim values option logic and the incoming claim type of Group and the outgoing claim type of Role is specified, all incoming claim values that flow in from the issuer are copied individually into new outgoing claims with claim type of Role.
Transforming a claim
In AD FS, the term claims transformation means to replace one incoming claim value with a different outgoing claim value. It is the Transform an Incoming Claim rule that makes this function possible. Within the properties of this rule, you can set conditions to transform incoming values with a different outgoing claim value based on the specified incoming claim type.
For example, as shown in the following illustration, when a rule is set with the condition to replace an incoming value with a different outgoing claim value, all incoming claim types of Group are mapped to new outgoing claim types of Role. In this case, the incoming claim value of Purchaser is replaced with the new outgoing claim value of Admin.
You can also use this rule to apply a condition that will replace all incoming claims with a specified e-mail suffix value with a new value. For example, you could set a condition in this rule to change all claim values with the suffix of sales.corp.fabrikam.com to fabrikam.com.
Configuring this rule on a claims provider trust
When you use a claims provider trust, this rule can be configured to transform incoming claims from the claims provider into trustworthy equivalents. Claim types or claim values can have a different meaning in your organization than in the claims provider organizations. You can use this rule to normalize the claim types and values that come from the claims provider so that their outgoing claim equivalents can be understood by the relying party.
Configuring this rule on a relying party trust
When you use a relying party trust, this rule can be configured to transform claims for the specific relying party. Claim types or claim values might have a different meaning for a specific relying party, and this rule makes it possible for you to change the outgoing claim types and values for a single relying party.
How to create this rule
You create this rule using either the claim rule language or using the Transform 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
Transform a specific incoming claim type to a specified outgoing claim type
Pass through all claim values
Replace an incoming claim value with a different outgoing claim value
Replace incoming e-mail suffix claims with a new e-mail suffix
For more instructions on how to create this template, see Create a Rule to Transform an Incoming Claim in the AD FS Deployment Guide.
Using the claim rule language
If the outgoing claim must be constructed from the content of more than one incoming claim, you must use a custom rule instead. If the claim value of the outgoing claim must be based on the value of the incoming claim—but with additional content—you must also use a custom rule in that context. For more information, see When to Use a Custom Claim Rule.
Examples of how to construct a transform rule syntax
When using the claim rule language syntax to transform claims, you can set a property of the transformed claim to a new literal value. For example, the following rule changes the value of role claims from "Administrators" to "root" while keeping the same claim type:
c:[type == "https://schemas.microsoft.com/ws/2008/06/identity/claims/role", value == "Administrators"] => issue(type = c.type, value = "root");
Regular expressions can also be used for claim transformations. For example, the following rule will set the domain in windows user name claims in DOMAIN\USER format to FABRIKAM:
c:[type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"] => issue(type = c.type, value = regexreplace(c.value, "(?<domain>[^\\]+)\\(?<user>.+)", "FABRIKAM\${user}"));
Best practices for creating custom rules
Claims transformations can be selectively applied to claims selected using basic filtering capabilities. Each of the claim properties used for filtering can be assigned values, with the following caveats:
| Claim property | Description |
|---|---|
| Type, Value, ValueType | These properties will be most frequently used for assignments. At the very least type and value must be specified for the resulting transformed claim. |
| Issuer | While the claim rule language allows setting the Issuer of a claim, this is generally not advisable. The issuer of a claim is not serialized in the token. When a token is received the Issuer property of all claims is set to the identifier of the federation server that signed the token. Thus, setting the issuer of a claim in the rules will not have effect on the contents of the token and the setting will be lost once the claim is packaged in a token. The only scenario where setting the issuer of a claim makes sense is if it is set to a specific value in the claims provider rule set and relying party rule set is authored with rules that reference this specific value. If the Issuer property is not explicitly set to a value in a claim rule the claims issuance engine sets it to "LOCAL AUTHORITY". |
| OriginalIssuer | Similarly to Issuer, OriginalIssuer should generally not be explicitly assigned a value. Unlike Issuer, the OriginalIssuer property is serialized in the token, but the expectation of token consumers is that, if set, it will contain the identifier of the federation server that originally issued a claim. |
| Properties | As outlined in the previous section, the Property bag of a claim is not persisted in the token, so assignments to properties should only be done if subsequent local policies are going to reference the information stored in the property. |
For more information about how to use the claim rule language, see The Role of the Claim Rule Language.