Working with ManagementPolicyRule Objects
Management policy in Forefront Identity Manager (FIM) is implemented by creating multiple ManagementPolicyRule objects in the system as described in Management Policy Example. A ManagementPolicyRule defines one or more events that can occur in the FIM system. With this object, you may also grant rights, connect workflows to an event, or both. When FIM receives requests through the FIM Service, FIM processes these requests as described in Request Processing. This topic provides additional information about how to work with ManagementPolicyRule objects, which control and define the processing rules used during FIM request processing.
ManagementPolicyRule Object Definition
A simplified definition for the ManagementPolicyRule would include the following code. Reflexive attributes such as PrincipalRelativeToResource are defined in a later section.
<ManagementPolicyRule>
<PrincipalSet/>
<ActionType/>
<ActionParameter/>
<ResourceCurrentSet/>
<ResourceFinalSet/>
<GrantRight/>
<AuthenticationWorkflowDefinition/>
<AuthorizationWorkflowDefinition/>
<ActionWorkflowDefinition/>
</ManagementPolicyRule>
In the previous definition, the first five elements 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 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:
<ManagementPolicyRule>
<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 object 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; 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:
<ManagementPolicyRule>
<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.
Modeling Transitions with ManagementPolicyRule Objects
ManagementPolicyRule objects can be created to model state transitions for your identity objects. For example, when a contractor is hired as a permanent employee or when a Developer becomes a Product Manager. You express transitions in ManagementPolicyRules as transitions in or out of Set objects. Example transitions are shown here. Rights or workflows could be added to these events. 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.
This example shows a transition event in which a user becomes part of a Set because of a Create() operation.
<ManagementPolicyRule>
<PrincipalSet>Reference to an "All Users" Set</PrincipalSet>
<ActionType>Create</ActionType>
<ActionParameter>*</ActionParameter>
<ResourceCurrentSet/>
<ResourceFinalSet>Reference to "All Users" Set</ResourceFinalSet>
<GrantRight>false</GrantRight>
</ManagementPolicyRule>
This example shows a transition event in which a person transitions from being a contractor/consultant for the company to becoming a full-time employee (FTE). This change is represented in the default schema by a change in the "EmployeeType" attribute of the Person.
<ManagementPolicyRule>
<PrincipalSet>Reference to "All Objects" Set</PrincipalSet>
<ActionType>Update</ActionType>
<ActionParameter>EmployeeType</ActionParameter>
<ResourceCurrentSet>Reference to custom "All Contractors" Set</ResourceCurrentSet>
<ResourceFinalSet>Reference to custom "All FTE Users" Set</ResourceFinalSet>
<GrantRight>false</GrantRight>
</ManagementPolicyRule>
Defining Reflexive Attributes
The "PrincipalSet", "ResourceCurrentSet" and "ResourceFinalSet" attributes of the ManagementPolicyRule objects are used when the principal (the users who the policy applies to) or the resource managed by the ManagementPolicyRule is a specific Set. Set objects 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 XPath Filter Language). 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.
<ManagementPolicyRule>
<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. This example assumes that the "All Users" set contains every Person. "PhoneNumber" is an attribute of a Person object in the default schema.
<ManagementPolicyRule>
<PrincipalSet>Reference to "All Users" 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.
Planning Use of ManagementPolicyRule Objects
Although a ManagementPolicyRule 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.
The following example defines a ManagementPolicyRule that links a workflow to an event without granting the associated permission. In this example, whenever a new executive is identified (through promotion, hiring or any other system update), a custom "Notify board of directors" workflow is run.
<ManagementPolicyRule>
<PrincipalSet>Reference to "All Users" Set</PrincipalSet>
<ActionType>Create</ActionType>
<ActionType>Update</ActionType>
<ActionParameter>*</ActionParameter>
<ResourceCurrentSet>Reference to "All Objects" Set</ResourceCurrentSet>
<ResourceFinalSet>Reference to custom "Executives" Set</ResourceFinalSet>
<GrantRight>false</GrantRight>
<ActionWorkflowDefinition>Reference to custom "Notify board of directors" WorkflowDefinition</ActionWorkflowDefinition>
</ManagementPolicyRule>
Rights/Permissions
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 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 objects, including the ManagementPolicyRule object 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.
<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.
<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?
GrantRight=true AND ManagementPolicyRule[PrincipalSet=/Set[ComputedMember=User1]
On what target object sets can user User1 perform a CREATE operation?
GrantRight=true AND ManagementPolicyRule[PrincipalSet=/Set[ComputedMember=User1] AND ActionType = "CREATE"
Can user User1 create objects of type "Group"?
GrantRight=true AND ManagementPolicyRule[PrincipalSet=/Set[ComputedMember=User1] AND ActionType = "CREATE" AND ResourceCurrentSet[/Set[ComputedMembers=/Group]]
Rights in Get() Operation
In order to obtain rights information from the server in response to a Get() request, the client must explicitly request rights information in the Get() request. WS-Addressing addresses consist of a URI (which in FIM is the URI of the Resource endpoint), together with reference parameters that identify the particular object that is being referenced. As an extension to WS-Transfer, the client can include the optional <IncludePermissionHints/> parameter to identify an object representation including rights information. This parameter does not take a value.
If a user performs a Get() request on the Resource Endpoint, the document at the address <ObjectID>x</ObjectID>< IncludePermissionHints ></ IncludePermissionHints > is the document representing the state of the object x with permission information attached.