|
| 1 | +--- |
| 2 | +title: API concepts in Privileged Identity management - Azure AD | Microsoft Docs |
| 3 | +description: Information for understanding the APIs in Azure AD Privileged Identity Management (PIM). |
| 4 | +services: active-directory |
| 5 | +documentationcenter: '' |
| 6 | +author: curtand |
| 7 | +manager: daveba |
| 8 | +editor: '' |
| 9 | +ms.service: active-directory |
| 10 | +ms.workload: identity |
| 11 | +ms.subservice: pim |
| 12 | +ms.topic: how-to |
| 13 | +ms.date: 05/04/2021 |
| 14 | +ms.author: curtand |
| 15 | +ms.custom: pim |
| 16 | +ms.collection: M365-identity-device-management |
| 17 | +--- |
| 18 | +# Understand the Privileged Identity Management APIs |
| 19 | + |
| 20 | +You can perform Privileged Identity Management (PIM) tasks using the Microsoft Graph APIs for Azure Active Directory (Azure AD) roles and the Azure Resource Manager API for Azure resource roles (sometimes called Azure RBAC roles). This article describes important concepts for using the APIs for Privileged Identity Management. |
| 21 | + |
| 22 | +For requests and other details about PIM APIs, check out: |
| 23 | + |
| 24 | +- PIM for Azure AD roles API reference |
| 25 | +- [PIM for Azure resource roles API reference](/rest/api/authorization/roleeligibilityschedulerequests) |
| 26 | + |
| 27 | +> [!IMPORTANT] |
| 28 | +> PIM APIs [!INCLUDE [PREVIEW BOILERPLATE](../../../includes/active-directory-develop-preview.md)] |
| 29 | +
|
| 30 | +## PIM API history |
| 31 | + |
| 32 | +There have been several iterations of the PIM API over the past few years. You'll find some overlaps in functionality, but they don't represent a linear progression of versions. |
| 33 | + |
| 34 | +### Iteration 1 – only supports Azure AD roles, deprecating |
| 35 | + |
| 36 | +Under the /beta/privilegedRoles endpoint, Microsoft had a classic version of the PIM API which is no longer supported in most tenants. We are in the process of deprecating remaining access to this API on 05/31. |
| 37 | + |
| 38 | +### Iteration 2 – supports Azure AD roles and Azure resource roles |
| 39 | + |
| 40 | +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 beta API will never be released to general availability and will be eventually deprecated. |
| 41 | + |
| 42 | +### Current iteration – Azure AD roles in Microsoft Graph and Azure resource roles in Azure Resource Manager |
| 43 | + |
| 44 | +Now in beta, Microsoft has the final iteration of the PIM API before we release the API to general availability. Based on customer feedback, the Azure AD PIM API is now under the unifiedRoleManagement set of API and the Azure Resource PIM API is now under the Azure Resource Manager role assignment API. These locations also provide a few additional benefits including: |
| 45 | + |
| 46 | +- Alignment of the PIM API for regular role assignment API for both Azure AD roles and Azure Resource roles. |
| 47 | +- Reducing the need to call additional PIM API to onboard a resource, get a resource, or get role definition. |
| 48 | +- Supporting app-only permissions. |
| 49 | +- New features such as approval and email notification configuration. |
| 50 | + |
| 51 | +In the current iteration, there is *no API support* for PIM alerts and privileged access groups. They are on the roadmap for future development. |
| 52 | + |
| 53 | +## Current permissions required |
| 54 | + |
| 55 | +- Azure AD roles |
| 56 | + |
| 57 | + To call the PIM Graph API for Azure AD roles, you will need at least one of the following permissions: |
| 58 | + |
| 59 | + - RoleManagement.ReadWrite.Directory |
| 60 | + - RoleManagement.Read.Directory |
| 61 | + |
| 62 | + The easiest way to specify the required permissions is to use the Azure AD consent framework. |
| 63 | + |
| 64 | +- Azure resource roles |
| 65 | + |
| 66 | + The PIM API for Azure resource roles is developed on top of the Azure Resource Manager framework. You will need to give consent to Azure Resource Management but won’t need any graph permission. You will 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 are trying to administer. |
| 67 | + |
| 68 | +## Calling PIM API with an app-only token |
| 69 | + |
| 70 | +- Azure AD roles |
| 71 | + |
| 72 | + PIM API now supports app-only permissions on top of delegated permissions. For app-only permissions, you must call the API with an application that's already been consented to the above permissions. For delegated permission, you must call the PIM API with both a user and an application token. The user must be assigned to either the Global Administrator role or Privileged Role Administrator role, and ensure that the service principal calling the API has at least the Owner or User Access Administrator role on the resource you are trying to administer. |
| 73 | + |
| 74 | +- Azure resource roles |
| 75 | + |
| 76 | + PIM API for Azure resources supports both user only and application only calls. Simply make sure the service principal has either the owner or user access administrator role on the resource. |
| 77 | + |
| 78 | +## Design of current API iteration |
| 79 | + |
| 80 | +PIM API consists of two categories that are consistent for both the API for Azure AD roles and Azure resource roles: assignment and activation API requests, and policy settings. |
| 81 | + |
| 82 | +### Assignment and activation API |
| 83 | + |
| 84 | +To make eligible assignments, time-bound eligible/active assignments, and to activate assignments, PIM provides the following entities: |
| 85 | + |
| 86 | +- RoleAssignmentSchedule |
| 87 | +- RoleEligibilitySchedule |
| 88 | +- RoleAssignmentScheduleInstance |
| 89 | +- RoleEligibilityScheduleInstance |
| 90 | +- RoleAssignmentScheduleRequest |
| 91 | +- RoleEligibilityScheduleRequest |
| 92 | + |
| 93 | +These entities work alongside pre-existing roleDefinition and roleAssignment entities for both Azure AD roles and Azure roles to allow you to create end to end scenarios. |
| 94 | + |
| 95 | +- If you are trying to create or retrieve a persistent (active) role assignment that does not have a schedule (start or end time), you should avoid these PIM entities and focus on the read/write operations under the roleAssignment entity |
| 96 | + |
| 97 | +- To create an eligible assignment with or without an expiration time you can use the write operation on roleEligibilityScheduleRequest |
| 98 | + |
| 99 | +- To create a persistent (active) assignment with a schedule (start or end time), you can use the write operation on roleAssignmentScheduleRequest |
| 100 | + |
| 101 | +- To activate an eligible assignment, you should also use the write operation on roleAssignmentScheduleRequest with a modified action parameter called selfActivate |
| 102 | + |
| 103 | +Each of the request objects would either create a roleAssignmentSchedule or a roleEligibilitySchedule object. These objects are read-only and show a schedule of all the current and future assignments. |
| 104 | + |
| 105 | +When an eligible assignment is activated, the roleEligibilityScheduleInstance continues to exist. The roleAssignmentScheduleRequest for the activation would create a separate roleAssignmentSchedule and roleAssignmentScheduleInstance for that activated duration. |
| 106 | + |
| 107 | +The instance objects are the actual assignments that currently exist whether it is an eligible assignment or an active assignment. You should use the GET operation on the instance entity to retrieve a list of eligible assignments / active assignments to a role/user. |
| 108 | + |
| 109 | +### Policy setting API |
| 110 | + |
| 111 | +To manage the setting, we provide the following entities: |
| 112 | + |
| 113 | +- roleManagementPolicy |
| 114 | +- roleManagementPolicyAssignment |
| 115 | + |
| 116 | +The *role management policy* defines the setting of the rule. For example, whether MFA/approval is required, whether and who to send the email notifications to, or whether permanent assignments are allowed or not. The *policy assignment* attaches the policy to a specific role. |
| 117 | + |
| 118 | +The two-entity design could support future scenarios such as attaching a policy to multiple roles. For now, use this API is to get a list of all the roleManagementPolicyAssignments, filter it by the roleDefinitionID you want to modify, and then update the policy associated with the policyAssignment. |
| 119 | + |
| 120 | +## Relationship between PIM entities and role assignment entities |
| 121 | + |
| 122 | +The only link between the PIM entity and the role assignment entity for persistent (active) assignment for either Azure AD roles or Azure roles is the roleAssignmentScheduleInstance. There is a one-to-one mapping between the two entities. That mapping means roleAssignment and roleAssignmentScheduleInstance would both include: |
| 123 | + |
| 124 | +- Persistent (active) assignments made outside of PIM |
| 125 | +- Persistent (active) assignments with a schedule made inside PIM |
| 126 | +- Activated eligible assignments |
| 127 | + |
| 128 | +## Next steps |
0 commit comments