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:
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 tenants 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.