Manage Microsoft Entra role assignments using PIM APIs

Privileged Identity Management (PIM) is a feature of Microsoft Entra ID Governance that enables you to manage, control, and monitor access to important resources in your organization. One method through which principals such as users, groups, and service principals (applications) are granted access to important resources is through assignment of Microsoft Entra administrator roles.

The PIM for Microsoft Entra roles APIs allow you to govern privileged access and limit excessive access to Microsoft Entra roles. This article introduces the governance capabilities of PIM for Microsoft Entra roles APIs in Microsoft Graph.

Note

To manage Azure resource roles use the PIM APIs for Azure Resource Manager.

Methods of assigning roles

PIM for Microsoft Entra roles provides two methods for assigning roles to principals:

• Active role assignments: A principal can have a permanent or temporary perpetually active role assignment.
• Eligible role assignments: A principal can be eligibile for a role either permanently or temporarily. With eligible assigments, the principal activates their role - thereby creating a temporarily active role assignment - when they need to perform privileged tasks. The activation is always time-bound for a maximum of 8 hours but the maximum duration can be lowered in the role settings. The activation can also be renewed or extended.

PIM APIs for managing active role assignments

PIM allows you to manage active role assignments by creating permanent assignments or temporary assignments. Use the unifiedRoleAssignmentScheduleRequest resource type and its related methods to manage role assignments.

Note

We recommend using PIM to manage active role assignments over using the unifiedRoleAssignment or the directoryRole resource types to manage them directly.

The following table lists scenarios for using PIM to manage role assignments and the APIs to call.

Scenarios	API
An administrator creates and assigns to a principal a permanent role assignment An administrator assigns to a principal a temporary role	Create roleAssignmentScheduleRequests
An administrator renews, updates, extends, or removes role assignments	Create roleAssignmentScheduleRequests
An administrator queries all role assignments and their details	List roleAssignmentScheduleRequests
An administrator queries a role assignment and its details	Get unifiedRoleAssignmentScheduleRequest
A principal queries their role assignments and the details	unifiedRoleAssignmentScheduleRequest: filterByCurrentUser
A principal performs just-in-time and time-bound activation of their eligible role assignment	Create roleAssignmentScheduleRequests
A principal cancels a role assignment request they created	unifiedRoleAssignmentScheduleRequest: cancel
A principal that has activated their eligible role assignment deactivates it when they no longer need access	Create roleAssignmentScheduleRequests
A principal deactivates, extends, or renews their own role assignment.	Create roleAssignmentScheduleRequests

PIM APIs for managing role eligibilities

Your principals may not require permanent role assignments because they don't require the privileges granted through the privileged role all the time. In this case, PIM also allows you to create role eligibilities and assign them to the principals. With role eligibilities, the principal activates the role when they need to perform privileged tasks. The activation is always time-bound for a maximum of 8 hours. The principal can also be permanently or temporarily eligible fot the role.

Use the unifiedRoleEligibilityScheduleRequest resource type and its related methods to manage role eligibilities.

The following table lists scenarios for using PIM to manage role eligibilities and the APIs to call.

Scenarios	API
An administrator creates and assigns to a principal an eligible role An administrator assigns a temporary role eligibility to a principal	Create roleEligibilityScheduleRequests
An administrator renews, updates, extends, or removes role eligibilities	Create roleEligibilityScheduleRequests
An administrator queries all role eligibilities and their details	List roleEligibilityScheduleRequests
An administrator queries a role eligibility and its details	Get unifiedRoleEligibilityScheduleRequest
An administrator cancels a role eligibility request they created	unifiedRoleEligibilityScheduleRequest: cancel
A principal queries their role eligibilities and the details	unifiedRoleEligibilityScheduleRequest: filterByCurrentUser
A principal deactivates, extends, or renews their own role eligibility.	Create roleEligibilityScheduleRequests

Role settings and PIM

Each Microsoft Entra role defines settings or rules. Such rules include whether multifactor authentication (MFA), justification, or approval is required to activate an eligible role, or whether you can create permanent assignments or eligibilities for principals to the role. These role-specific rules determine the settings you can apply while creating or managing role assignments and eligibilities through PIM.

In Microsoft Graph, these rules are managed through the unifiedRoleManagementPolicy and the unifiedRoleManagementPolicyAssignment resource types and their related methods.

For example, assume that by default, a role doesn't allow permanent active assignments and defines a maximum of 15 days for active assignments. Attempting to create a unifiedRoleAssignmentScheduleRequest object without expiry date returns a 400 Bad Request response code for violation of the expiration rule.

PIM allows you to configure various rules including:

• Whether principals can be assigned permanent eligible assignments
• The maximum duration allowed for a role activation and whether justification or approval is required to activate eligible roles
• The users who are allowed to approve activation requests for a Microsoft Entra role
• Whether MFA is required to both activate and enforce a role assignment
• The principals who get notified of role activations

The following table lists scenarios for using PIM to manage rules for Microsoft Entra roles and the APIs to call.

Scenarios	API
Retrieve role management policies and associated rules or settings	List unifiedRoleManagementPolicies
Retrieve a role management policy and its associated rules or settings	Get unifiedRoleManagementPolicy
Update a role management policy on its associated rules or settings	Update unifiedRoleManagementPolicy
Retrieve the rules defined for role management policy	List rules
Retrieve a rule defined for a role management policy	Get unifiedRoleManagementPolicyRule
Update a rule defined for a role management policy	Update unifiedRoleManagementPolicyRule
Get the details of all role management policy assignments including the policies and rules or settings associated with the Microsoft Entra roles	List unifiedRoleManagementPolicyAssignments
Get the details of a role management policy assignment including the policy and rules or settings associated with the Microsoft Entra role	Get unifiedRoleManagementPolicyAssignment

For more information about using Microsoft Graph to configure rules, see Overview of rules for Microsoft Entra roles in PIM APIs in Microsoft Graph. For examples of updating rules, see Use PIM APIs in Microsoft Graph to update Microsoft Entra ID rules.

Security alerts for Microsoft Entra roles

PIM for Microsoft Entra roles generates alerts when it detects suspicious or unsafe settings for Microsoft Entra roles in your tenant. The following seven alert types are available:

Alert	Microsoft Graph resources (alert configuration / incidents)
Too many global administrators in the tenant	tooManyGlobalAdminsAssignedToTenantAlertConfiguration / tooManyGlobalAdminsAssignedToTenantAlertIncident
Invalid license alerts that limit the use of PIM	invalidLicenseAlertConfiguration / invalidLicenseAlertIncident
Roles configured for activation without requiring multifactor authentication	noMfaOnRoleActivationAlertConfiguration / noMfaOnRoleActivationAlertIncident
Users with unused eligible or active Microsoft Entra role assignments	redundantAssignmentAlertConfiguration / redundantAssignmentAlertIncident
Microsoft Entra roles being assigned outside of Privileged Identity Management	rolesAssignedOutsidePrivilegedIdentityManagementAlertConfiguration / rolesAssignedOutsidePrivilegedIdentityManagementAlertIncident
Microsoft Entra roles being activated too frequently	sequentialActivationRenewalsAlertConfiguration / sequentialActivationRenewalsAlertIncident
Potential stale accounts in a privileged role	staleSignInAlertConfiguration / staleSignInAlertIncident

For more information about these alerts including the severity rating and triggers, see, Configure security alerts for Microsoft Entra roles in PIM.

Building blocks of the PIM alerts APIs

Use the following Microsoft Graph resources to manage PIM alerts.

Resource	Description	API operations
unifiedRoleManagementAlert	Provides a summary of alerts in PIM for Microsoft Entra roles, whether they're enabled or disabled, when the PIM service last scanned the tenant for incidences or this alert, and the number of incidences mapping to this alert type in the tenant. The PIM service scans the tenant daily for incidences relating to the alert but you can also run a manual scan.	List Get Update Refresh (Manual scan)
unifiedRoleManagementAlertDefinition	Provides detailed description of each alert type, the severity level, the recommended steps to mitigate incidences relating to the alert in the tenant, and the recommended actions to prevent future incidences.	List Get
unifiedRoleManagementAlertConfiguration	The tenant-specific configuration for the alert including whether the PIM service should scan the tenant for incidences relating to the alert, the thresholds that trigger the alert, and the related alert definition. This is an abstract type from which resources that represent the individual alert types are derived.	List Get Update
unifiedRoleManagementAlertIncident	The incidences in the tenant that match the alert type.	List Get Remediate

For more information about working with security alerts for Microsoft Entra roles using PIM APIs, see Manage security alerts for Microsoft Entra roles using PIM APIs in Microsoft Graph.

Audit logs

All activities made through PIM for Microsoft Entra roles are logged in Microsoft Entra audit logs and you can read through the List directory audits API.

Zero Trust

This feature helps organizations to align their identities with the three guiding principles of a Zero Trust architecture:

• Verify explicitly
• Use least privilege
• Assume breach

To find out more about Zero Trust and other ways to align your organization to the guiding principles, see the Zero Trust Guidance Center.

Licensing

The tenant where Privileged Identity Management is being used must have enough purchased or trial licenses. For more information, see Microsoft Entra ID Governance licensing fundamentals.

Related content

• To learn more about security operations, see Microsoft Entra security operations for Privileged Identity Management in the Microsoft Entra architecture center.