Rule Groups and Rules
Updated: June 19, 2015
Applies To: Azure
In Microsoft Azure Active Directory Access Control (also known as Access Control Service or ACS), a rule group is a named set of claim rules that define which identity claims are passed from identity providers to your relying party application. In ACS, rule groups are associated 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.
When ACS receives a token request or a token from an identity provider, it runs through all of the rule groups associated with the relying party application to process the claims in the token. All rule groups are run through simultaneously, as are all rules in each rule group (order does not matter). If the rules cause any new claims to be issued after the run is complete, then the rule groups associated with the relying party application are run through again. Rule and rule group run process stops when no new claims are issued after the run process completes or after ACS completes ten run through’s (whichever comes first).
You can create and edit rule groups and rules either manually, using the ACS Management Portal or programmatically, using the ACS Management Service.
Configuring Rules with the ACS Management Portal
Creating Rule Groups
When you add and configure the properties of a new relying party application in the ACS Management Portal, you can also create a rule group associated with this relying party application, because by default, the Create New Rule Group option is checked in the Add Relying Party Application page of the ACS Management Portal. We strongly recommend that you keep this option selected and thus create a default rule group for your new relying party application. (For more information, see “Rule groups” in Relying Party Applications.) You can also add rule groups using the Rule Groups section of the ACS Management Portal. Then, as you add relying party applications using the Add Relying Party Application page, you can associate them with one or more existing rule groups.
Generating Rules
After a rule group is created, you can use the Edit Rule Group page of the ACS Management Portal to automatically generate rules. If you decide to generate rules automatically, you are prompted to select the identity providers for which you want to generate the rules. When the rule group is linked to one or more relying party applications, the identity providers used by those relying party applications are selected by default.
Note
For WS-Federation identity providers, a rule is created for each claim type that is offered in the identity provider’s WS-Federation metadata and this rule passes through the claim type and value. For other identity providers, pass-through rules are generated based on a list of predetermined claim types.
Viewing, Adding, and Editing Rules
The Edit Rule Group page of the ACS Management Portal displays all of the rules in a table, where the columns include the Output Claim for the rule, the Claim Issuer (can be an identity provider or ACS), and a Description.
If you click a given rule in the table you are redirected to the Edit Claim Rule page, where the rule may be edited. To add a new rule manually, you can click Add.
Claim Rules
Claim rules describe the logic of how ACS transforms input claims into output claims. Rules are contained within rule groups, which are associated with relying party applications and are run through whenever a token is issued by ACS for an application. If a rule group contains no rules, then no token is issued to the relying party application. Typically, one rule is required for every claim type that you want to issue to your relying party application. It is possible to create and use only one rule to pass through all claim types and values. However, using a rule per every claim type improves security and provides greater control over the data that is passed to your application.
In ACS, you can configure a rule to pass a claim received from an identity provider or client through to the relying party application without changing the claim’s type, issuer, or value. These rules are called pass-through rules. For example, tokens issued by Windows Live ID (Microsoft account) contain a nameidentifier claim type. To pass this claim unchanged to the relying party application, you have to configure a pass-through rule that processes the input nameidentifier claim type from the claim issuer, Windows Live ID, and creates an identical output claim.
The table below illustrates claims being passed through from a fictional AD FS 2.0 identity provider named Contoso.com.
| Input Claims | Output Claims | ||||
|---|---|---|---|---|---|
|
Issuer |
Type |
Value |
Issuer |
Type |
Value |
|
Contoso.com |
https://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier |
123456789 |
Access Control Service |
https://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier |
123456789 |
|
Contoso.com |
https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress |
john@contoso.com |
Access Control Service |
https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress |
john@contoso.com |
|
Contoso.com |
https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name |
John Doe |
Access Control Service |
https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name |
John Doe |
The ACS rules engine also provides you with the ability to transform input claims into entirely different output claims, based on the claim issuer, input claim type, and value. In other words, the ACS rules engine allows you to transform input tokens into different output tokens by adding, removing, or changing the claims that the tokens contain. This form of claims transformation makes ACS capable of implementing basic authorization based on claim input values. The example below shows a claim type of “role” with a value of “administrator” being output if the “nameidentifier” input claim matches a specific value.
| Input Claims | Output Claims | ||||
|---|---|---|---|---|---|
|
Issuer |
Type |
Value |
Issuer |
Type |
Value |
|
Contoso.com |
https://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier |
123456789 |
Access Control Service |
https://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier |
administrator |
The ACS rules engine also provides the ability to create output claims based on a conjunction of two input claims. In the example below, the output claim is of type “action” with a value of “write” if both the “nameidentifier” and the “role” input claims from Contoso.com match specific values. When two input claims are specified in a rule, both values must match to generate the output claim.
| Input Claims | Ouutput Claims | ||||
|---|---|---|---|---|---|
|
Issuer |
Type |
Value |
Issuer |
Type |
Value |
|
Contoso.com |
https://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier |
123456789 |
Access Control Service
|
https://schemas.xmlsoap.org/ws/2005/05/identity/claims/action
|
write
|
|
Contoso.com |
https://schemas.xmlsoap.org/ws/2005/05/identity/claims/role |
administrator |
|||
For more information and steps about how to implement token transformation using rules, see How to: Implement Token Transformation Logic Using Rules.
When you add new or edit existing claim rules with the ACS Management Portal, you must configure the following settings:
Rule conditions (if) – Adding an Input Claim
This section contains the conditions that must be true for the rule to issue an output claim. These conditions include the following:
Claim issuer—Refers to the entity that issued the input claim. This can be a configured identity provider (for example, ) or ACS. ACS is the issuer if the input claim comes from a service identity or the input claim comes from another claim rule. For more information, see Service Identities.
Input claim type—Refers to the input claim type received from the claim issuer. For example, the full claim type for the “nameidentifier” is https://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier. The options for this field include:
Any—Returns true if any claim type is received from the issuer.
Select type—Returns true if the input claim type matches the type selected in the drop-down menu. This menu is populated with available claim types for the selected claim issuer.
Enter type—Returns true if the input claim type matches the exact value entered in the field.
Important
This field is case-sensitive.
Input claim value—Refers to the value of the input claim received. For example, the “nameidentifier” claim type uses an email address as its value and this field can be used to check for a specific email address. The options for this field include:
Any—Returns true if any claim value is received from the issuer.
Enter value—Returns true if the input claim type matches the exact value entered in the field. This option requires a specific input claim type to be selected or entered in the Input Claim Type field.
Important
This field is case-sensitive.
Rule conditions (if) – Adding a Second Input Claim
To add a second claim to the rule, click Add a second input claim. This allows you to specify the additional conditions shown below. Note that in a rule with two input claims, all conditions must be true to generate an output claim.
Claim issuer—Refers to the entity that issued the second input claim. This can be the same identity provider selected for the first claim, or it can be ACS. Select ACS to specify claims generated from other claim rules during rules processing.
Important
Two different identity providers cannot be selected for the first and second claims, as rules processing only occurs for one token issued from one identity provider at a time.
Input claim type—Refers to the input claim type received from the claim issuer. For example, the full claim type for the “nameidentifier” is https://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier. The options for this field include:
Select type—Returns true if the input claim type matches the type selected in the drop-down menu. This menu is populated with available claim types for the selected claim issuer.
Enter type—Returns true if the input claim type matches the exact value entered in the field.
Important
This field is case-sensitive.
Input claim value—Refers to the value of the input claim received. For example, the “nameidentifier” claim type uses an email address as its value and this field can be used to check for a specific email address. This returns true if the input claim type matches the exact value entered in the field.
Important
This field is case-sensitive.
Rule actions (then)
This section specifies the output claim that is issued by ACS if the conditions in the If section of the rule are true. The output claim options include the following:
Output claim type—The claim type that is issued by ACS. The options for this field include the following:
Pass-through input claim type—Issues an output claim that is of the same type as the input claim.
Select type—Issues an output claim of the specified type. The drop-down menu contains a list of common claim types.
Enter type—Issues a claim of the entered type. If the output claim is to be present in a SAML token, then this value must be a URI (for example, https://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier).
Important
This field is case-sensitive.
Output claim value—Refers to the value of the output claim issued by ACS. The options for this field include the following:
Pass-through input claim value—Issues an output claim with the value identical to the value of the input claim.
Enter value—Issues a claim that has the value entered in this field. This option requires a specific input claim type to be selected or entered in the Output Claim Type field.
Important
This field is case-sensitive.
Rule Information
You can use this section to create a description for a rule.
Note
In ACS, rule descriptions are not automatically created for the generated rules.
Configuring Rules with the ACS Management Service
Rules in an Access Control namespace can be configured programmatically by using the ACS Management Service. For an example of how to configure rules by using ASP.NET, see Code Sample: Management Service. Below are important items to consider when using the ACS Management Service to configure rules:
When editing and deleting rules in a rule group, it is recommended that you first query ACS for all rules within that rule group, and use the rule IDs that your query returns to perform the edit or delete operations. It is not recommended that you store the IDs returned by the management service for future operations, as these IDs are not guaranteed to persist.
If you are writing automatic retry logic for creating rules (such as in the event of a timeout), it is recommended that you first query for the existence of an identical rule in the current rule group before attempting to add it a second time.