Overview of role management through the privileged identity management (PIM) API

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. This access is enabled through privileged roles and role-based access control (RBAC) and can be granted to users, groups, or service principals. The resources can be in Azure AD, Azure, and other Microsoft cloud services such as Microsoft 365 or Microsoft Intune.

The Microsoft Graph PIM API for role management allows you to govern privileged access and limit excessive access. This article introduces the governance capabilities of PIM APIs in Microsoft Graph.

Note

To manage Azure resource roles use the Azure Resource Manager (ARM) APIs for PIM.

PIM API for managing 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 API 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 settings 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 settings will determine the settings you can apply while creating or managing role assignments and eligibilities through PIM. In Microsoft Graph, these role settings 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.

The following table lists scenarios for using PIM to manage Azure AD role settings or 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 or settings defined for role management policy List rules
Retrieve a rule or settings defined for a role management policy Get unifiedRoleManagementPolicyRule
Update a rule or setting 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 role settings, see Configure Azure AD role settings in Privileged Identity Management.

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 user 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 principal 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 PIM API requires an Azure AD Premium P2 license. For more information, see License requirements to use Privileged Identity Management.

See also