A simplified definition for a Request Management Policy Rule (see ManagementPolicyRuleType Property) resource would include the following code. Reflexive attributes such as PrincipalRelativeToResource are defined in a later section.

	Copy Code
<ManagementPolicyRule> <ManagementPolicyRuleType>Request</ManagementPolicyRuleType> <PrincipalSet/> <ActionType/> <ActionParameter/> <ResourceCurrentSet/> <ResourceFinalSet/> <GrantRight/> <AuthenticationWorkflowDefinition/> <AuthorizationWorkflowDefinition/> <ActionWorkflowDefinition/> </ManagementPolicyRule>

In the previous definition, the first five elements after the <ManagementPolicyRuleType> define the condition when the management policy is applicable. The remaining elements define whether the management policy grants rights and references additional workflows that must be run when the event occurs. For example, the following ManagementPolicyRule resource defines an event in which a user updates the groupType of a Group and the updated group will be part of an All Distribution Groups Set resource:

Copy Code

<ManagementPolicyRule> <ManagementPolicyRuleType>Request</ManagementPolicyRuleType> <PrincipalSet>Reference to All Users Set</PrincipalSet> <ActionType>Modify</ActionType> <ActionParameter>groupType</ActionParameter> <ResourceCurrentSet>Reference to All Groups Set</ResourceCurrentSet> <ResourceFinalSet>Reference to All Distribution Groups Set</ResourceFinalSet> <GrantRight>false</GrantRight> <AuthenticationWorkflowDefinition/> <AuthorizationWorkflowDefinition/> <ActionWorkflowDefinition/> </ManagementPolicyRule>

Note that all elements in these examples that are of type Reference are GUID values, but are described here for clarity (see Schema Data Types).

The above example defines a condition and associates a workflow with the event but does not grant, nor deny, any rights to the PrincipalSet to perform any actions (since GrantRight=false) and does not associate any workflows with the event. This example will be extended in a subsequent example in this section.

In FIM, users can only perform actions (make requests to the FIM Service database) if they have been granted permissions/rights to perform that action; all other requests are denied. In the previous example, the ManagementPolicyRule does not grant, nor deny, any rights to the PrincipalSet to perform any actions (since GrantRight=false). We can modify the previous example to grant rights to enable members of the "All Users" Set to perform the action by setting "GrantRight" = true. We can also create a ManagementPolicyRule resource that references workflows so that the workflows are run every time that the event defined in the ManagementPolicyRule object occurs (workflows are ignored for Read and Enumerate requests; see Request Processing for more information). For this example we will assume that we have also created two WorkflowDefinition resources; one that defines a workflow that requires approval from group owners before the change is made (an Authorization workflow) and one that notifies e-mail system administrators after the change is made (an Action workflow). This more complex version of the ManagementPolicyRule object would resemble the following:

Copy Code

<ManagementPolicyRule> <ManagementPolicyRuleType>Request</ManagementPolicyRuleType> <PrincipalSet>Reference to "All Users" Set</PrincipalSet> <ActionType>Update</ActionType> <ActionParameter>groupType</ActionParameter> <ResourceCurrentSet>Reference to "All Groups" Set</ResourceCurrentSet> <ResourceFinalSet>Reference to "All Distribution Groups" Set</ResourceFinalSet> <GrantRight>true</GrantRight> <AuthenticationWorkflowDefinition/> <AuthorizationWorkflowDefinition>Reference to a custom "Group owners approval" WorkflowDefinition</AuthorizationWorkflowDefinition> <ActionWorkflowDefinition/>Reference to "Email system administrator notification" WorkflowDefinition<ActionWorkflowDefinition/> </ManagementPolicyRule>

These elements are multi-valued: action type, actions, action parameters, and workflows.

The * value is used in the "ActionType" element to indicate that the ManagementPolicyRule applies to all action types (see ManagementPolicyRule). The * value is ActionParameter attributes to indicate that the ManagementPolicyRule applies to all attributes of the objects in the Set referenced by the "PrincipalSet" element.

ManagementPolicyRule resources can be created to model state transitions for your identity objects and associate action workflows with those state transitions. An example state transition is when an employee is hired, promoted or fired. You express transitions in ManagementPolicyRules as transitions in or out of Set resources. Action workflows can be added to the MPRs.

The following example shows a transition in which a person transitions into being a full-time employee (FTE). That change is represented in the default schema by a change in the "EmployeeType" attribute of the Person resource. An action workflow to add the user to a mailing list is run whenever the MPR is triggered.

Copy Code

<ManagementPolicyRule> <ManagementPolicyRuleType>SetTransition</ManagementPolicyRuleType> <PrincipalSet>Reference to "All People" Set</PrincipalSet> <ActionType>TransitionIn</ActionType> <ActionParameter>EmployeeType</ActionParameter> <ResourceFinalSet>Reference to custom "All full-time employees (FTE)" Set</ResourceFinalSet> <GrantRight>false</GrantRight> <ActionWorkflowDefinition>Reference to a custom "Add user to 'full-time employees' mailing list" workflow</ActionWorkflowDefinition> </ManagementPolicyRule>

The above example models people are transitioning into a set so <ActionType> is set to "TransitionIn" and the <ResourceFinalSet> represents the set that the resource is transitioning into. We could create a similar MPR in which people were transitioning out of the set of full time employees. In that case, the <ActionType> would be "TransitionOut" and the <ResourceCurrentSet> element would be used instead of the <ResourceFinalSet> element.

The following is an example of a Set Transition MPR that is based on a calculation of time passed. In this example, the MPR is triggered when an employee has an expiration date of greater than one week ago.

Copy Code

<ManagementPolicyRule> <ManagementPolicyRuleType>SetTransition</ManagementPolicyRuleType> <PrincipalSet>Reference to "All People" Set</Principal> <ActionType>TransitionIn</ActionType> <ActionParameter>EmployeeExpirationDate</ActionParameter> <ResourceFinalSet>Reference to a custom "All People with EmployeeExpirationDate of at least one week" Set</ResourceCurrentSet> <GrantRight>false</GrantRight> <Disabled>false</Disabled> <ActionWorkflowDefinition>Reference to a custom “Archive User's Mailbox."</ActionWorkflowDefinition> </ManagementPolicyRule>

For more information, see ManagementPolicyRuleType Property.

The "PrincipalSet", "ResourceCurrentSet" and "ResourceFinalSet" attributes of the ManagementPolicyRule resources are used when the principal (the users who the policy applies to) or the resource managed by the ManagementPolicyRule is a specific Set resource. Set resources can be created to represent static and dynamic sets such as "All Groups," "All Contactors," or even "All inactive users who have start dates earlier than 2008" (see FIM XPath Filter Dialect). The "PrincipalSet", "CurrentSet" and "FinalSet" attributes are optional attributes because each has an alternate attribute that can be used in its position to indicate a relationship between the principal and resource. These reflexive attributes include PrincpalSetRelativeToResource, ResourceCurrentSetRelativeToResource and ResourceFinalRelativeToResource. The value for each attribute is a string value that represents the name of an attribute on the target object.

Example: Only the owners of a group can modify the "DisplayName" attribute of the Group.

Copy Code

<ManagementPolicyRule> <ManagementPolicyRuleType>Request</ManagementPolicyRuleType> <PrincipalRelativeToResource>Owners</PrincipalRelativeToResource> <ActionType>Update</ActionType> <ActionParameter>DisplayName</ActionParameter> <ResourceCurrentSet>Reference to custom "Locked Groups" Set</ResourceCurrentSet> <ResourceFinalSet>Reference to custom "Locked Groups" Set</ResourceFinalSet> <GrantRight>true</GrantRight> </ManagementPolicyRule>

Example: Users can update their own telephone number. "PhoneNumber" is an attribute of a Person object in the default schema.

Copy Code

<ManagementPolicyRule> <ManagementPolicyRuleType>Request</ManagementPolicyRuleType> <PrincipalSet>Reference to "All People" Set</PrincipalSet> <ActionType>Update</ActionType> <ActionParameter>PhoneNumber</ActionParameter> <ResourceCurrentSetRelativeToPrincipal>ObjectId</ResourceCurrentSetRelativeToPrincipal > <ResourceFinalRelativeToPrincipal>ObjectId</ResourceFinalRelativeToPrincipal> <GrantRight>true</GrantRight> </ManagementPolicyRule>

See ManagementPolicyRule for more information about the use of reflexive attributes.

Although a ManagementPolicyRule resource may both grant rights and map associated workflows, a 1 to 1 relationship between ManagementPolicyRule objects and events or workflows is not always desirable. You might want to define multiple specific permissions for objects and attributes on those objects by defining those permissions in multiple ManagementPolicyRule objects. However, you might also want to create a ManagementPolicyRule object that defines a broad category of events and common workflows that should be run every time any one of those events occurs but does not grant any rights.

You should also create ManagementPolicyRule objects which grant read rights separately from those which grant other rights, if those other rights have any attached workflows, since those workflows will not be evaluated when performing a read.

Granting Rights

The "GrantRight" attribute of a ManagementPolicyRule must be set to true for the object to grant rights. The existence of only a single ManagementPolicyRule object matching the event criteria and having "GrantRight" = true will cause the request to pass the "ManagementPolicyRule Evaluation" step in Request Processing).

As stated earlier, a ManagementPolicyRule resource can grant rights, map workflows to the event, or both. This makes it possible to define an event and later add workflows or rights to the event. Because rights on FIM resources, including the ManagementPolicyRule resource itself, can be specified on the attribute level, it is possible to configure FIM to allow one set of administrators to design and manage user rights and authorization workflows and a different group of administrators to manage action workflows. It is also possible to restrict the users who can have read access to these objects.

The following ManagementPolicyRule object grants rights but does not use any workflows. In this example, the object grants all users the rights to create groups.

	Copy Code
<ManagementPolicyRule> <PrincipalSet>Reference to custom "All Users" Set</PrincipalSet> <ActionType>Create</ActionType> <ActionParameter>*</ActionParameter> <ResourceFinalSet>Reference to "All Groups" Set</ResourceFinalSet> <GrantRight>true</GrantRight> </ManagementPolicyRule>

Querying for Rights

It is possible to determine what rights a user has by creating a WS-Transfer Get() request (see Web Services Overview) that includes ManagementPolicyRule objects. However, only users who have rights to read ManagementPolicyRule objects will be able to query for rights information. The following ManagementPolicyRule object grants authenticated users rights to query rights information.

	Copy Code
<ManagementPolicyRule> <PrincipalSet>Reference to "All Authenticated Users" Set</PrincipalSet> <Actions>Read</Actions> <ActionParameters>*</ActionParameters> <ResourceCurrentSet>Reference to "All ManagementPolicyRule Objects" Set</ResourceCurrentSet> <ResourceFinalSet>Reference to default "Any" Set</ResourceFinalSet> <GrantRight>true</GrantRight> </ManagementPolicyRule>

The following are examples of XPath queries that could be used as part of WS-Resource Get() message (see Web Services Overview) to query for rights.

What operations can User1 perform?

	Copy Code
GrantRight=true AND ManagementPolicyRule[PrincipalSet=/Set[ComputedMember=User1]

On what target object sets can user User1 perform a CREATE operation?

	Copy Code
GrantRight=true AND ManagementPolicyRule[PrincipalSet=/Set[ComputedMember=User1] AND ActionType = "CREATE"

Can user User1 create objects of type "Group"?

	Copy Code
GrantRight=true AND ManagementPolicyRule[PrincipalSet=/Set[ComputedMember=User1] AND ActionType = "CREATE" AND ResourceCurrentSet[/Set[ComputedMembers=/Group]]

Note that the above examples will not capture the case in which user rights are affected by the "PrincipalRelativeToResource" attribute.

Rights in Get() Operation

Concepts