Create a Rule to Transform an Incoming Claim

By using the Transform an Incoming Claim rule template in Active Directory Federation Services (AD FS), you can select an incoming claim, change its claim type, and change its claim value. For example, you can use this rule template to create a rule that sends a role claim with the same claim value of an incoming group claim. You can also use this rule to send a group claim with a claim value of Purchasers when there is an incoming group claim with a value of Admins, or you can send only user principal name (UPN) claims that end with @fabrikam.

You can use the following procedure to create a claim rule with the AD FS Management snap-in.

Membership in Administrators, or equivalent, on the local computer is the minimum requirement to complete this procedure. Review details about using the appropriate accounts and group memberships at Local and Domain Default Groups.

To create a rule to transform an incoming claim on a Relying Party Trust in Windows Server 2016

  1. In Server Manager, click Tools, and then select AD FS Management.

  2. In the console tree, under AD FS, click Relying Party Trusts. Screenshot that shows where to select Relying Party Trusts when you create a rule to transform an incoming claim on a Relying Party Trust in Windows Server 2016.

  3. Right-click the selected trust, and then click Edit Claim Issuance Policy. Screenshot that shows where to select Edit Claim Issuance Policy when you create a rule to transform an incoming claim on a Relying Party Trust in Windows Server 2016.

  4. In the Edit Claim Issuance Policy dialog box, under Issuance Transform Rules click Add Rule to start the rule wizard. Screenshot that shows where to select Add Rule when you create a rule to transform an incoming claim on a Relying Party Trust in Windows Server 2016.

  5. On the Select Rule Template page, under Claim rule template, select Transform an Incoming Claim from the list, and then click Next. Screenshot that shows where to select the Transform an Incoming Claim when you create a rule to transform an incoming claim on a Relying Party Trust in Windows Server 2016.

  6. On the Configure Rule page, under Claim rule name, type the display name for this rule. In Incoming claim type, select a claim type in the list. In Outgoing claim type, select a claim type in the list, and then select one of the following options, which depends on the requirements of your organization:

    • 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 Screenshot that shows where to type the claim rule name when you create a rule to transform an incoming claim on a Relying Party Trust in Windows Server 2016.

  7. Click the Finish button.

  8. In the Edit Claim Rules dialog box, click OK to save the rule.

Note

If you are setting up the Dynamic Access Control scenario that uses AD FS-issued claims, first create a transform rule on the claims provider trust, and in Incoming claim type, type the name for the incoming claim, or, if a claim description was previously created, select it from the list. Second, in Outgoing claim type, select the claim URL that you want, and then create a transform rule on the relying party trust to issue the device claim.

For more information about Dynamic Access Control scenarios, see Dynamic Access Control Content Roadmap or Using AD DS Claims with AD FS.

To create a rule to transform an incoming claim on a Claims Provider Trust in Windows Server 2016

  1. In Server Manager, click Tools, and then select AD FS Management.

  2. In the console tree, under AD FS, click Claims Provider Trusts. Screenshot that shows where to select Claims Provider Trusts when you create a rule to transform an incoming claim on a Claims Provider Trust in Windows Server 2016.

  3. Right-click the selected trust, and then click Edit Claim Rules. Screenshot that shows where to select Edit Claim Rules when you create a rule to transform an incoming claim on a Claims Provider Trust in Windows Server 2016.

  4. In the Edit Claim Rules dialog box, under Acceptance Transform Rules click Add Rule to start the rule wizard. Screenshot that shows where to select Add Rule when you create a rule to transform an incoming claim on a Claims Provider Trust in Windows Server 2016.

  5. On the Select Rule Template page, under Claim rule template, select Transform an Incoming Claim from the list, and then click Next. Screenshot that shows where to select the Transform an Incoming Claim template when you create a rule to transform an incoming claim on a Claims Provider Trust in Windows Server 2016.

  6. On the Configure Rule page, under Claim rule name, type the display name for this rule. In Incoming claim type, select a claim type in the list. In Outgoing claim type, select a claim type in the list, and then select one of the following options, which depends on the requirements of your organization:

    • 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 Screenshot that shows where to type the claim rule name when you create a rule to transform an incoming claim on a Claims Provider Trust in Windows Server 2016.

  7. Click the Finish button.

  8. In the Edit Claim Rules dialog box, click OK to save the rule.

Note

If you are setting up the Dynamic Access Control scenario that uses AD FS-issued claims, first create a transform rule on the claims provider trust, and in Incoming claim type, type the name for the incoming claim, or, if a claim description was previously created, select it from the list. Second, in Outgoing claim type, select the claim URL that you want, and then create a transform rule on the relying party trust to issue the device claim.

For more information about Dynamic Access Control scenarios, see Dynamic Access Control Content Roadmap or Using AD DS Claims with AD FS.

To create a rule to transform an incoming claim in Windows Server 2012 R2

  1. In Server Manager, click Tools, and then click AD FS Management.

  2. In the console tree, under AD FS\Trust Relationships, click either Claims Provider Trusts or Relying Party Trusts, and then click a specific trust in the list where you want to create this rule.

  3. Right-click the selected trust, and then click Edit Claim Rules. Screenshot that shows where to select Edit Claim Rules when you create a rule in Windows Server 2012 R2.

  4. In the Edit Claim Rules dialog box, select one the following tabs, which depends on the trust that you are editing and in which rule set you want to create this rule, and then click Add Rule to start the rule wizard that is associated with that rule set:

    • Acceptance Transform Rules

    • Issuance Transform Rules

    • Issuance Authorization Rules

    • Delegation Authorization Rules Screenshot that shows where to select Edit Claim Rules when you create a rule to transform an incoming claim in Windows Server 2012 R2.

  5. On the Select Rule Template page, under Claim rule template, select Transform an Incoming Claim from the list, and then click Next. Screenshot that shows where to select the Transform an Incoming Claim template when you create a rule to transform an incoming claim in Windows Server 2012 R2.

  6. On the Configure Rule page, under Claim rule name, type the display name for this rule. In Incoming claim type, select a claim type in the list. In Outgoing claim type, select a claim type in the list, and then select one of the following options, which depends on the requirements of your organization:

    • 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 create rule

Note

If you are setting up the Dynamic Access Control scenario that uses AD FS-issued claims, first create a transform rule on the claims provider trust, and in Incoming claim type, type the name for the incoming claim, or, if a claim description was previously created, select it from the list. Second, in Outgoing claim type, select the claim URL that you want, and then create a transform rule on the relying party trust to issue the device claim.

For more information about Dynamic Access Control scenarios, see Dynamic Access Control Content Roadmap or Using AD DS Claims with AD FS.

  1. Click Finish.

  2. In the Edit Claim Rules dialog box, click OK to save the rule.

Additional references

Configure Claim Rules

Checklist: Creating Claim Rules for a Relying Party Trust

Checklist: Creating Claim Rules for a Claims Provider Trust

When to Use an Authorization Claim Rule

The Role of Claims

The Role of Claim Rules