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 security alerts for Azure AD roles are available on the
beta endpoint only. For more information, see Security alerts for Azure AD 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.
|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.
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|
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.
Permissions and privileges
- 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 tenant where Privileged Identity Management is being used must have sufficient purchased or trial licenses. For more information, see License requirements to use Privileged Identity Management.
- What is Azure AD Privileged Identity Management?
- Learn more about role settings in PIM through the following articles:
- Follow these tutorials to learn more about using PIM APIs