Manage Azure AD role assignments using PIM APIs

Article
08/22/2023

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.

Note

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.

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

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
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. For examples of updating rules, see Use PIM APIs to update Azure AD rules.

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.

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:
- RoleAssignmentSchedule.ReadWrite.Directory
- RoleEligibilitySchedule.ReadWrite.Directory
- RoleManagement.ReadWrite.Directory

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.

Licensing

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.