How to: Implement Token Transformation Logic Using Rules

Updated: June 19, 2015

Applies To: Azure

Applies To

• Microsoft Azure Active Directory Access Control (also known as Access Control Service or ACS)

Summary

This topic describes how to use the ACS Management Portal to create rules that transform input claims into output claims.

Contents

• Objectives

• Overview

• Summary of Steps

• Step 1 – Navigate to the Rule Groups Page of the Management Portal

• Step 2 – Auto-Generate New Rules

• Step 3 – Create Pass-Through Rules

• Step 4 – Create Advanced Transformation Rules

• Step 5 – Review the Available Rule Groups

• Step 6 – Configure the Relying Party to Use for Specific Rule Groups

Objectives

• Become familiar with the Access Control Management Portal section related to claims transformation rules.

• Create basic rules.

• Create advanced rules.

• Create rules based on identity provider claims.

• Create rules based on ACS claims.

Overview

Claim rules describe the logic for transforming ACS input claims into output claims. Rules are contained in rule groups that are associated with relying party applications. The rules are executed whenever a token is issued to ACS for the relying party application. If a rule group does not contain any rules, ACS does not issue tokens to the relying party application.

Summary of Steps

To create rules for token claims transformation, use the following steps. Note that some of the steps are optional in some scenarios.

• Step 1 – Navigate to the Rule Groups Page of the Management Portal

• Step 2 – Auto-Generate New Rules

• Step 3 – Create Pass-Through Rules

• Step 4 – Create Advanced Transformation Rules

• Step 5 – Review the Available Rule Groups

• Step 6 – Configure the Relying Party to Use for Specific Rule Groups

Step 1 – Navigate to the Rule Groups Page of the Management Portal

This step shows you how to navigate to the Rule Groups page of the Management Portal where rules are created and added to the rule groups.

To navigate to the Rule Groups page of the Management Portal

1. Go to the Microsoft Azure Management Portal (https://manage.WindowsAzure.com), sign in, and then click Active Directory. (Troubleshooting tip: "Active Directory" item is missing or not available)

2. To create an Access Control namespace, click New, click App Services, click Access Control, and then click Quick Create. (Or, click Access Control Namespaces before clicking New.)

3. To manage an Access Control namespace, select the namespace, and then click Manage. (Or, click Access Control Namespaces, select the namespace, and then click Manage.)

4. On the Access Control Service page, click Rule groups.

Step 2 – Auto-Generate New Rules

This step shows you how to generate basic default rules.

To auto-generate basic rules

1. Click Rule groups.

2. To create a new rule group, on the Rule Groups page, click Add.

3. Type a name for the new rule group, and then click Save.

4. To auto-generate basic rules, click Generate rules.

5. On the Generate rules page, specify the identity provider in the check box next to the rule you want to generate, and then click Generate.

6. Review the automatically generated rules. For example, the rules that are generated automatically for Google and Windows Live ID (Microsoft account)would look similar to the results in the following table.) If the identity provider appears, click Save.

   Output claim	Claim issuer	Rule description
   emailaddress	Google	Pass-through "emailaddress" claim from Google as "emailaddress"
   name	Google	Pass-through "name" claim from Google as "name"
   nameidentifier	Google	Pass-through "nameidentifier" claim from Google as "nameidentifier"
   nameidentifier	Windows Live ID	Pass-through "nameidentifier" claim from Windows Live ID as "nameidentifier"

7. If you do not see desired identity provider, you should return to the Identity Providers page of the Management Portal and specify it.

8. To add identity providers follow the steps outlined in the following How-To topics:

   • How to: Configure Google as an Identity Provider

   • How to: Configure Yahoo! as an Identity Provider

   • How to: Configure Facebook as an Identity Provider

   • How to: Configure AD FS 2.0 as an Identity Provider

Step 3 – Create Pass-Through Rules

This step shows you how to create pass-through rules. A pass-through rule is one where the outgoing claims are exactly the same as incoming claims.

To create pass-through rules

1. Click Rule groups.

2. On the Rule groups page, click the desired rule group, and then click Add.

3. On the Add Claim Rule page, specify the following attributes:

   • Claims issuer—Choose your desired identity provider from the drop-down list (for example, Google or Windows Live ID) or click the Access Control Service radio button.

   • (And) Input claim type—Specify either Any for all incoming claims or choose a specific claim type from the drop-down list.

   • (And) Input claim value—Specify Any for all claims values to be passed through or specify a specific claim value in the Enter Value box to only pass through the one specified.

   • Output claim type—Specify a specific claim type by selecting the Pass through input claim type radio button.

   • Output claim value—Specify a specific claim value by selecting the Pass through input claim value radio button.

   • Optionally, (recommended) you can add a description for the rule, and then click Save.

Step 4 – Create Advanced Transformation Rules

This step shows how to create advanced transformation rules as opposed to auto-generated and pass-through rules.

To create advanced transformation rules

1. Click Rule groups.

2. On the Rule groups page, click the desired rule group and then click Add.

3. On the Add Claim Rule page, specify the following attributes:

   • Claims issuer—Select the specific Identity Provider radio button if you want to transform claims from identity providers, such as Windows Live ID, Google, Facebook, and Yahoo! Select Access Control Service if you want to transform claims of service identities (in the case of Web Services) or the claims output from other rules.

   • (And) Input claim type—Select the type of the claim you wish to transform from the drop-down box or if it is not listed there, enter the claim type in the Enter type text box.

   • (And) Input claim value—Specify a specific value in the Enter value text box if you wish to transform a claim that matches this value only.

   • Output claim type—Select the type of the output claim you wish to map to the incoming claim or if it is not listed there, enter the claim type in the Enter type text box.

   • Output claim value—Specify a specific value in the Enter Value text box if you wish to generate a constant value in the output claim.

Step 5 – Review the Available Rule Groups

This step shows you how to review rule groups that contain claims transformation rules. Rule groups are associated directly with relying party applications. A rule group can be used by more than one relying party application and a relying party application can reference more than one rule group. To review the available rule groups, follow the steps outlined previously in Step 1 – Navigate to the Rule Groups Page of the Management Portal.

Step 6 – Configure a Relying Party to Use for Specific Rule Groups

This step sows how to set specific rule groups for a relying party (a web application or RESTful web service).

To configure a relying party to use for specific rule groups

1. Go to the Microsoft Azure Management Portal (https://manage.WindowsAzure.com), sign in, and then click Active Directory. (Troubleshooting tip: "Active Directory" item is missing or not available)

2. To manage an Access Control namespace, select the namespace, and then click Manage. (Or, click Access Control Namespaces, select the namespace, and then click Manage.)

3. Click Relying party applications.

4. On the Relying party applications page, click the desired relying party.

5. Scroll down to the Rule Groups section, and then check all of rule groups you wish to apply for this relying party.

6. Click Save.