Modifica

Manage Microsoft Entra role assignments using PIM APIs

  • Articolo

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 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 Azure Resource Manager (ARM) APIs for PIM.

PIM APIs for managing security alerts for Microsoft Entra roles are available on the beta endpoint only. For more information, see Security alerts for Microsoft Entra roles.

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.

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 may not 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 role eligibility can also be a permanent eligibility or a temporary eligibility.

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. For examples of updating rules, see Use PIM APIs to update rules for Microsoft Entra ID roles.

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