Rules in PIM - Mapping guide
Privileged Identity Management (PIM) exposes role settings for the resources that can be managed. In Microsoft Graph, these resources are Microsoft Entra roles and groups and they're managed through PIM for Microsoft Entra roles and PIM for groups respectively.
Role settings fall in one of three categories:
- Activation settings
- Assignment settings
- Notification settings
Such settings include whether multifactor authentication (MFA) is required to activate an eligible role or group membership; or whether you can create permanent role assignments, group ownership, or group memberships.
When using the PIM for Microsoft Entra roles APIs or PIM for groups APIs in Microsoft Graph, these role settings are managed through policies and rules.
Policies
In Microsoft Graph, the role settings are called rules. These rules are grouped in, assigned to, and managed for Microsoft Entra roles and groups through containers called policies.
The policies are defined through the unifiedRoleManagementPolicy resource type.
Policy rules
Each unifiedRoleManagementPolicy object contains 17 predefined rules that can be updated. These rules are managed through the rules relationship.
Microsoft Graph defines the unifiedRoleManagementPolicyRule resource type abstract type, which is inherited by five resources. The five derived types are used to group the rules into activation, assignment, and notification rules. They define rule configurations that can be one or more of 17 rules that are identified by unique and immutable rule IDs.
This article provides a mapping of settings in PIM on the Microsoft Entra admin center to the corresponding rules in Microsoft Graph.
Mapping of rule IDs to PIM role settings on the Microsoft Entra admin center
Activation rules
The following image shows the activation role settings on the Microsoft Entra admin center, mapped to rules and resource types in the PIM APIs in Microsoft Graph.
| Number | Microsoft Entra admin center UX Description | Microsoft Graph rule ID / Derived resource type | Enforced for caller |
|---|---|---|---|
| 1 | Activation maximum duration (hours) | Expiration_EndUser_Assignment / unifiedRoleManagementPolicyExpirationRule |
End user |
| 2 | On activation, require: None, Azure MFA Require ticket information on activation Require justification on activation |
Enablement_EndUser_Assignment / unifiedRoleManagementPolicyExpirationRule |
End user |
| 3 | On activation, require: Microsoft Entra Conditional Access authentication context (Preview) | AuthenticationContext_EndUser_Assignment / unifiedRoleManagementPolicyExpirationRule |
End user |
| 4 | Require approval to activate | Approval_EndUser_Assignment / unifiedRoleManagementPolicyExpirationRule |
End user |
Assignment rules
The following image shows the assignment role settings on the Microsoft Entra admin center, mapped to rules and resource types in the PIM API in Microsoft Graph.
| Number | Microsoft Entra admin center UX Description | Microsoft Graph Rule ID / Derived resource type | Enforced for caller |
|---|---|---|---|
| 5 | Allow permanent eligible assignment Expire eligible assignments after |
Expiration_Admin_Eligibility / unifiedRoleManagementPolicyExpirationRule |
Admin |
| 6 | Allow permanent active assignment Expire active assignments after |
Expiration_Admin_Assignment / unifiedRoleManagementPolicyExpirationRule |
Admin |
| 7 | Require Azure Multi-Factor Authentication on active assignment Require justification on active assignment |
Enablement_Admin_Assignment / unifiedRoleManagementPolicyExpirationRule |
Admin |
| 8 | Does not exist in Microsoft Entra admin center UX | Enablement_Admin_Eligibility / unifiedRoleManagementPolicyExpirationRule |
Admin |
Notification rules
The following image shows the notification role settings on the Microsoft Entra admin center, mapped to rules and resource types in the PIM API in Microsoft Graph.
| Number | Microsoft Entra admin center UX Description | Microsoft Graph Rule ID / Derived resource type | Enforced for caller |
|---|---|---|---|
| 9 | Send notifications when members are assigned as eligible to this role: Role assignment alert | Notification_Admin_Admin_Eligibility / unifiedRoleManagementPolicyExpirationRule |
Admin |
| 10 | Send notifications when members are assigned as eligible to this role: Notification to the assigned user (assignee) | Notification_Requestor_Admin_Eligibility / unifiedRoleManagementPolicyExpirationRule |
Assignee / Requestor |
| 11 | Send notifications when members are assigned as eligible to this role: request to approve a role assignment renewal/extension | Notification_Approver_Admin_Eligibility / unifiedRoleManagementPolicyExpirationRule |
Approver |
| 12 | Send notifications when members are assigned as active to this role: Role assignment alert | Notification_Admin_Admin_Assignment / unifiedRoleManagementPolicyExpirationRule |
Admin |
| 13 | Send notifications when members are assigned as active to this role: Notification to the assigned user (assignee) | Notification_Requestor_Admin_Assignment / unifiedRoleManagementPolicyExpirationRule |
Assignee / Requestor |
| 14 | Send notifications when members are assigned as active to this role: Request to approve a role assignment renewal/extension | Notification_Approver_Admin_Assignment / unifiedRoleManagementPolicyExpirationRule |
Approver |
| 15 | Send notifications when eligible members activate this role: Role activation alert | Notification_Admin_EndUser_Assignment / unifiedRoleManagementPolicyExpirationRule |
Admin |
| 16 | Send notifications when eligible members activate this role: Notification to activated user (requestor) | Notification_Requestor_EndUser_Assignment / unifiedRoleManagementPolicyExpirationRule |
Requestor |
| 17 | Send notifications when eligible members activate this role: Request to approve an activation | Notification_Approver_EndUser_Assignment / unifiedRoleManagementPolicyExpirationRule |
Approver |