Rules in PIM - mapping guide

Privileged Identity Management (PIM) exposes role settings or rules for the resources that can be managed. In Microsoft Graph, these resources are Microsoft Entra roles and groups and they are managed through PIM for Microsoft Entra roles and PIM for groups respectively.

Role settings fall in one of three categories: activation settings, assignment settings, and notification settings. Such settings include whether multifactor authentication (MFA) is required to activate an eligible role, group membership or group ownership, or whether you can create permanent role assignments or permanent group membership or ownership.

When using the PIM 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 policy contains 17 pre-defined rules that can be updated. These rules are managed through the rules relationship of the unifiedRoleManagementPolicy resource type.

To group the rules into activation, assignment, and notification rules, Microsoft Graph defines the unifiedRoleManagementPolicyRule resource type abstract type. This abstract type is inherited by five resources. Each of these five derived types then defines rule configurations that can be one or more of 17 rules. The 17 rules 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_Admin_Eligibility / unifiedRoleManagementPolicyEnablementRule	Admin
3	On activation, require: Microsoft Entra Conditional Access authentication context (Preview)	AuthenticationContext_EndUser_Assignment / unifiedRoleManagementPolicyAuthenticationContextRule	End user
4	Require approval to activate	Approval_EndUser_Assignment / unifiedRoleManagementPolicyApprovalRule	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 Require ticket information on activation	Enablement_Admin_Assignment / unifiedRoleManagementPolicyExpirationRule	Admin
8	Require Azure Multi-Factor Authentication on active assignment Require justification on active assignment Require ticket information on activation	Enablement_EndUser_Assignment / unifiedRoleManagementPolicyExpirationRule	End user

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 / unifiedRoleManagementPolicyNotificationRule	Admin
10	Send notifications when members are assigned as eligible to this role: Notification to the assigned user (assignee)	Notification_Requestor_Admin_Eligibility / unifiedRoleManagementPolicyNotificationRule	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 / unifiedRoleManagementPolicyNotificationRule	Approver
12	Send notifications when members are assigned as active to this role: Role assignment alert	Notification_Admin_Admin_Assignment / unifiedRoleManagementPolicyNotificationRule	Admin
13	Send notifications when members are assigned as active to this role: Notification to the assigned user (assignee)	Notification_Requestor_Admin_Assignment / unifiedRoleManagementPolicyNotificationRule	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 / unifiedRoleManagementPolicyNotificationRule	Approver
15	Send notifications when eligible members activate this role: Role activation alert	Notification_Admin_EndUser_Assignment / unifiedRoleManagementPolicyNotificationRule	Admin
16	Send notifications when eligible members activate this role: Notification to activated user (requestor)	Notification_Requestor_EndUser_Assignment / unifiedRoleManagementPolicyNotificationRule	Requestor
17	Send notifications when eligible members activate this role: Request to approve an activation	Notification_Approver_EndUser_Assignment / unifiedRoleManagementPolicyNotificationRule	Approver

Related content

• Overview of role management through the privileged identity management (PIM) API
• Use PIM APIs in Microsoft Graph to update rules
• Configure role settings in Privileged Identity Management using the Microsoft Entra admin center