Manage Azure AD role assignments using PIM APIs
Privileged Identity Management (PIM) is a feature of Azure AD Identity 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 Azure AD roles.
The PIM for Azure AD roles APIs allow you to govern privileged access and limit excessive access to Azure AD roles. This article introduces the governance capabilities of PIM for Azure AD roles APIs in Microsoft Graph.
To manage Azure resource roles use the Azure Resource Manager (ARM) APIs for PIM.
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.
|An administrator creates and assigns to a principal a permanent role assignment
An administrator assigns to a principal a temporary role
|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.
|An administrator creates and assigns to a principal an eligible role
An administrator assigns a temporary role eligibility to a principal
|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 Azure AD 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 will 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 will return a
400 Bad Request response code for violation of the expiration rule.
PIM allows you to configure various rules including the following:
- 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 an Azure AD 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 Azure AD rules and the APIs to call.
|Retrieve role management policies and associated rules or settings||List unifiedRoleManagementPolicies|
|Retrieve a role management policy and its associated rules or settings||Get 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 Azure AD roles||List unifiedRoleManagementPolicyAssignments|
|Get the details of a role management policy assignment including the policy and rules or settings associated with the Azure AD role||Get unifiedRoleManagementPolicyAssignment|
For more information about using Microsoft Graph to configure rules, see Overview of rules for Azure AD roles in PIM APIs in Microsoft Graph. For examples of updating rules, see Use PIM APIs in Microsoft Graph to update Azure AD rules.
PIM and identity security with Zero Trust
PIM APIs support organizations to adopt a Zero Trust approach to secure the identities in their organization. For more information about Zero Trust, see Securing identity with Zero Trust.
Permissions and privileges
To call the Create roleAssignmentScheduleRequests and Create roleEligibilityScheduleRequests APIs with admin actions, the calling app must:
- Have a Global Administrator or Privileged Role Administrator role
- Be granted one of the following permissions:
The app must also be assigned the appropriate permissions to retrieve their role assignments and eligibilities, or call the Create roleAssignmentScheduleRequests and Create roleEligibilityScheduleRequests APIs with user actions.
For more information about permissions to call PIM APIs, see the Microsoft Graph permissions reference: Role management permissions.
The PIM API requires an Azure AD Premium P2 license. For more information, see License requirements to use Privileged Identity Management.
- What is Azure AD Identity Governance?
- What is Azure AD Privileged Identity Management?
- Tutorial: Use the Privileged Identity Management (PIM) API to assign Azure AD roles
- You can also set up access reviews of role assignments and eligibilities that are managed through PIM. For more information, see Tutorial: Use the Privileged Identity Management (PIM) API to assign Azure AD roles.
Submit and view feedback for