Use Azure PIM to manage eligible access with the REST API

Azure Privileged Identity Management (PIM) enables you to limit standing administrator access to privileged roles, discover who has access, and review privileged access. This article describes the common ways to manage access using the REST API.

List eligible assignments

To list eligible role assignments (list access), you can use one of the Role Eligibility Schedule Instances - List For Scope or Role Eligibility Schedules - List For Scope REST APIs. To refine your results, you specify a scope and an optional filter. To call the API, you must have access to the Microsoft.Authorization/roleAssignments/read operation at the specified scope. All built-in roles are granted access to this operation.

Important

The difference between schedules and schedule instances is that while schedule instances only include assignments that are active at the current time, schedules also include assignments that will become active in the future.

1. Start with the following request:

   GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleEligibilityScheduleInstances?api-version=2020-10-01&$filter={filter}
   

   GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleEligibilitySchedules?api-version=2020-10-01&$filter={filter}
   

2. Within the URI, replace {scope} with the scope for which you want to list the role assignments.

   Scope	Type
   providers/Microsoft.Management/managementGroups/{mg-name}	Management Group
   subscriptions/{subscriptionId}	Subscription
   subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1	Resource group
   subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/providers/Microsoft.Web/sites/mysite1	Resource

3. Replace {filter} with the condition that you want to apply to filter the role assignment list.

   Filter	Description
   $filter=atScope()	List role assignments for only the specified scope, not including the role assignments at subscopes.
   $filter=principalId%20eq%20'{objectId}'	List role assignments for a specified user, group, or service principal.
   $filter=roleDefinitionId%20eq%20'{roleDefinitionId}'	List role assignments for a specified role definition.
   $filter=assignedTo('{objectId}')	List role assignments for a specified user, including ones inherited from groups.
   $filter=asTarget()	List role assignments for the current user or service principal, including ones inherited from groups.
   $filter=assignedTo('{objectId}')+and+atScope()	List role assignments for a specified user, including ones inherited from groups for only the specified scope, not including the role assignments at subscopes.

Grant eligible assignment

To create an eligible role assignment (grant access), you use the Role Eligibility Schedule Requests - Create REST API and specify the security principal, role definition, schedule, requestType = AdminAssign and scope. To call this API, you must have access to Microsoft.Authorization/roleAssignments/write operation. Of the built-in roles, only Owner and User Access Administrator are granted access to this operation.

1. Use the Role Definitions - List REST API or see Built-in roles to get the identifier for the role definition you want to assign.

2. Use a GUID tool to generate a unique identifier that will be used for the role assignment identifier. The identifier has the format: 00000000-0000-0000-0000-000000000000

3. Start with the following request and body:

   PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleEligibilityScheduleRequests/{roleEligibilityScheduleRequestName}?api-version=2020-10-01
   

   {
     "Properties": {
       "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
       "PrincipalId": "{principalId}",
       "RequestType": "AdminAssign",
       "ScheduleInfo": {
         "StartDateTime": "2020-09-09T21:31:27.91Z",
         "Expiration": {
           "Type": "AfterDuration", // Values: AfterDuration, AfterDateTime, NoExpiration
           "EndDateTime": null,
           "Duration": "P365D" // Use ISO 8601 format
         }
       }
     }
   }
   

4. Within the URI, replace {scope} with the scope for the role assignment.

   Scope	Type
   providers/Microsoft.Management/managementGroups/{mg-name}	Management Group
   subscriptions/{subscriptionId}	Subscription
   subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1	Resource group
   subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/providers/Microsoft.Web/sites/mysite1	Resource

5. Replace {roleEligibilityScheduleRequestName} with the GUID identifier of the role assignment.

6. Within the request body, replace {subscriptionId} with your subscription identifier.

7. Replace {roleDefinitionId} with the role definition identifier.

8. Replace {principalId} with the object identifier of the user, group, or service principal that will be assigned the role.

Remove eligible assignment

To remove an eligible role assignment (remove access), use the Role Eligibility Schedule Requests - Create REST API to create a new request to revoke assignment and specify the security principal, role definition, requestType = AdminRemove and scope. To call this API, you must have access to the Microsoft.Authorization/roleAssignments/write operation. Of the built-in roles, only Owner and User Access Administrator are granted access to this operation.

1. Use a GUID tool to generate a unique identifier that will be used for the role assignment identifier. The identifier has the format: 00000000-0000-0000-0000-000000000000

2. Start with the following request:

   PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleEligibilityScheduleRequests/{roleEligibilityScheduleRequestName}?api-version=2020-10-01
   

   {
     "Properties": {
       "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
       "PrincipalId": "{principalId}",
       "RequestType": "AdminRemove"
       }
   }
   

3. Within the URI, replace {scope} with the scope for removing the role assignment.

   Scope	Type
   providers/Microsoft.Management/managementGroups/{mg-name}	Management Group
   subscriptions/{subscriptionId}	Subscription
   subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1	Resource group
   subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1	Resource

4. Replace {roleEligibilityScheduleRequestName} with the GUID identifier of the role assignment.

Common errors returned for a new request

Following is a list of common errors that you may encounter while creating a new request and how to mitigate them.

Error Message	Explanantion	Mitigation
code: RoleAssignmentExists message: The Role assignment already exists.	A similar role assignment already exists	You can GET this role assignment and verify its schedule.
code: RoleAssignmentRequestPolicyValidationFailed message: The following policy rules failed: ["ExpirationRule"]	The ScheduleInfo specified in the request exceeds the maximum allowed duration	You can GET the RoleManagementPolicy for this RoleDefinitionId and check the RoleManagementPolicyExpirationRule
code: RoleAssignmentRequestPolicyValidationFailed message: The following policy rules failed: ["JustificationRule"]	You need to specify a Justification in the request body	You can GET the RoleManagementPolicy for this RoleDefinitionId and check the RoleManagementPolicyEnablementRule
code: RoleAssignmentRequestPolicyValidationFailed message: The following policy rules failed: ["EligibilityRule"]	A valid RoleEligibilityScheduleInstance doesn't exist to activate this role	A resource admin needs to create a RoleEligibilityScheduleRequest for this principal
code: RoleAssignmentRequestPolicyValidationFailed message: The following policy rules failed: ["TicketingRule"]	You need to specify a TicketInfo in the request body	You can GET the RoleManagementPolicy for this RoleDefinitionId and check the RoleManagementPolicyEnablementRule
code: RoleAssignmentRequestPolicyValidationFailed message: The following policy rules failed: ["MfaRule"]	You need to complete Azure Multi-Factor Authentication to submit this request	You can GET the RoleManagementPolicy for this RoleDefinitionId and check the RoleManagementPolicyEnablementRule