Privileged Identity Management APIs
Privileged Identity Management (PIM), part of Microsoft Entra, includes three providers:
- PIM for Microsoft Entra roles
- PIM for Azure resources
- PIM for Groups
You can manage assignments in PIM for Microsoft Entra roles and PIM for Groups using Microsoft Graph. You can manage assignments in PIM for Azure Resources using Azure Resource Manager APIs. This article describes important concepts for using the APIs for Privileged Identity Management.
Find more details about APIs that allow to manage assignments in the documentation:
- PIM for Microsoft Entra roles API reference
- PIM for Azure resource roles API reference
- PIM for Groups API reference
- PIM Alerts for Microsoft Entra roles API reference
- PIM Alerts for Azure Resources API reference
There have been several iterations of the PIM APIs over the past few years. There are some overlaps in functionality, but they don't represent a linear progression of versions.
Under the /beta/privilegedRoles
endpoint, Microsoft had a classic version of the PIM API, which only supported Microsoft Entra roles and is no longer supported. Access to this API was deprecated in June 2021.
Under the /beta/privilegedAccess
endpoint, Microsoft supported both /aadRoles
and /azureResources
. This endpoint is still available in your tenant but Microsoft recommends against starting any new development with this API. This API will never be released to general availability and will eventually be deprecated.
Iteration 3 (Current) – PIM for Microsoft Entra roles, groups in Microsoft Graph API, and for Azure resources in ARM API
This is the final iteration of the PIM API. It includes:
- PIM for Microsoft Entra roles in Microsoft Graph API - Generally available.
- PIM for Azure resources in ARM API - Generally available.
- PIM for groups in Microsoft Graph API - Generally available.
- PIM alerts for Microsoft Entra roles in Microsoft Graph API - Preview.
- PIM alerts for Azure Resources in ARM API - Preview.
Having PIM for Microsoft Entra roles in Microsoft Graph API and PIM for Azure Resources in ARM API provide a few benefits including:
- Alignment of the PIM APIs for regular role assignment for both Microsoft Entra roles and Azure Resource roles.
- Reducing the need to call other PIM APIs to onboard a resource, get a resource, or get role definition.
- Supporting app-only permissions.
- New features such as approval and email notification configuration.
PIM APIs across providers (both Microsoft Graph APIs and ARM APIs) follow the same principles.
To create assignment (active or eligible), renew, extend, of update assignment (active or eligible), activate eligible assignment, deactivate eligible assignment, use resources *AssignmentScheduleRequest and *EligibilityScheduleRequest:
- For Microsoft Entra roles: unifiedRoleAssignmentScheduleRequest, unifiedRoleEligibilityScheduleRequest;
- For Azure resources: Role Assignment Schedule Request, Role Eligibility Schedule Request;
- For Groups: privilegedAccessGroupAssignmentScheduleRequest, privilegedAccessGroupEligibilityScheduleRequest.
Creation of *AssignmentScheduleRequest or *EligibilityScheduleRequest objects may lead to creation of read-only *AssignmentSchedule, *EligibilitySchedule, *AssignmentScheduleInstance, and *EligibilityScheduleInstance objects.
- *AssignmentSchedule and *EligibilitySchedule objects show current assignments and requests for assignments to be created in the future.
- *AssignmentScheduleInstance and *EligibilityScheduleInstance objects show current assignments only.
When an eligible assignment is activated (Create *AssignmentScheduleRequest was called), the *EligibilityScheduleInstance continues to exist, new *AssignmentSchedule and a *AssignmentScheduleInstance objects are created for that activated duration.
For more information about assignment and activation APIs, see PIM API for managing role assignments and eligibilities.
To manage the PIM policies, use *roleManagementPolicy and *roleManagementPolicyAssignment entities:
- For PIM for Microsoft Entra roles, PIM for Groups: unifiedroleManagementPolicy, unifiedroleManagementPolicyAssignment
- For PIM for Azure resources: Role Management Policies, Role Management Policy Assignments
The *roleManagementPolicy resource includes rules that constitute PIM policy: approval requirements, maximum activation duration, notification settings, and so on.
The *roleManagementPolicyAssignment object attaches the policy to a specific role.
For more information about the policy settings APIs, see role settings and PIM.
For Microsoft Graph permissions required for PIM for Microsoft Entra roles, see the corresponding REST API reference pages.
The PIM APIs for Azure resource roles is developed on top of the Azure Resource Manager framework. You need to consent to Azure Resource Management but don’t need any Microsoft Graph permissions. You also need to make sure the user or the service principal calling the API has at least the Owner or User Access Administrator role on the resource you're trying to administer.
For Microsoft Graph permissions required for PIM for Groups, see the corresponding REST API reference pages.
The only link between the PIM entity and the role assignment entity for persistent (active) assignment for either Microsoft Entra roles or Azure roles is the *AssignmentScheduleInstance. There's a one-to-one mapping between the two entities. That mapping means roleAssignment and *AssignmentScheduleInstance would both include:
- Persistent (active) assignments made outside of PIM
- Persistent (active) assignments with a schedule made inside PIM
- Activated eligible assignments
PIM-specific properties (such as end time) will be available only through *AssignmentScheduleInstance object.