Privileged Identity Management APIs

  • Article

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 API history

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.

Iteration 1 - Deprecated

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.

Iteration 2 - Supports Microsoft Entra roles and Azure resource roles

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.

Overview of PIM API iteration 3

PIM APIs across providers (both Microsoft Graph APIs and ARM APIs) follow the same principles.

Assignments management

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:

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.

PIM Policies (role settings)

To manage the PIM policies, use *roleManagementPolicy and *roleManagementPolicyAssignment entities:

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.

Permissions

PIM for Microsoft Entra roles

For Microsoft Graph permissions required for PIM for Microsoft Entra roles, see the corresponding REST API reference pages.

PIM for Azure resources

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.

PIM for Groups

For Microsoft Graph permissions required for PIM for Groups, see the corresponding REST API reference pages.

Relationship between PIM entities and role assignment entities

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.

Next steps