Use Azure PIM to manage active 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 active assignments
To list active role assignments (list access), you can use one of the Role Assignment Schedule Instances - List For Scope or Role Assignment 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.
Start with the following request:
GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleInstances?api-version=2020-10-01&$filter={filter}
GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentSchedules?api-version=2020-10-01&$filter={filter}
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 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 active assignment
To create an active role assignment (grant access), you use the Role Assignment 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.
Use the Role Definitions - List REST API or see Built-in roles to get the identifier for the role definition you want to assign.
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
Start with the following request and body:
PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?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": "P30D" // Use ISO 8601 format } } } }
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 Replace {roleAssignmentScheduleRequestName} with the GUID identifier of the role assignment.
Within the request body, replace {subscriptionId} with your subscription identifier.
Replace {roleDefinitionId} with the role definition identifier.
Replace {principalId} with the object identifier of the user, group, or service principal that will be assigned the role.
Remove active assignment
To remove an active role assignment (remove access), use the Role Assignment 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.
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
Start with the following request:
PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?api-version=2020-10-01
{ "Properties": { "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}", "PrincipalId": "{principalId}", "RequestType": "AdminRemove" } }
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 Replace {roleAssignmentScheduleRequestName} with the GUID identifier of the role assignment.
Activate an eligible role assignment
To activate an eligible role assignment (gain activated access), use the Role Assignment Schedule Requests - Create REST API to create a new request and specify the security principal, role definition, requestType = SelfActivate
and scope. To call this API, you must have an eligible role assignment on the scope.
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
[Optional] Choose a
RoleEligibilitySchedule
that you want to activate and get theRoleEligibilityScheduleId
from the Role Eligibility Schedules API to pass in as theLinkedRoleEligibilityScheduleId
. This is optional, and if not passed the system will pick aRoleEligibilitySchedule
.Start with the following request:
PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?api-version=2020-10-01
{ "Properties": { "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}", "PrincipalId": "{principalId}", "RequestType": "SelfActivate", "ScheduleInfo": { "StartDateTime": "2020-09-09T21:31:27.91Z", "Expiration": { "Type": "AfterDuration", // Values: AfterDuration, AfterDateTime, NoExpiration "EndDateTime": null, "Duration": "PT8H" // Use ISO 8601 format } }, "LinkedRoleEligibilityScheduleId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleAssignmentSchedules/{roleAssignmentScheduleId}" //Optional } }
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 Replace {roleAssignmentScheduleRequestName} with the GUID identifier of the role assignment.
Deactivate an active role assignment
To de-activate an activated role assignment (remove activated access), use the Role Assignment Schedule Requests - Create REST API to create a new request and specify the security principal, role definition, requestType = SelfDeactivate
and scope. To call this API, you must have an activated role assignment on the scope.
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
Start with the following request:
PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?api-version=2020-10-01
{ "Properties": { "RoleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}", "PrincipalId": "{principalId}", "RequestType": "SelfDeactivate" } }
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 Replace {roleAssignmentScheduleRequestName} with the GUID identifier of the role assignment.
Just-Enough-Access (JEA)
If a user has an eligible role assignment at a resource (parent), they can choose to activate the role at a child level scope of the parent resource instead of the entire parent scope. For example, if a user has Contributor
eligible role at a subscription, they can activate the role at a child resource group level of the subscription.
To get a list of all children of a resource on which you have eligible access you can use the Eligible Child Resources API.
Start with the following request:
GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/eligibleChildResources?api-version=2020-10-01&$filter={filter}
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 Replace {filter} with the condition that you want to apply to filter the role assignment list.
Filter Description $filter=resourceType+eq+'Subscription'
List resources of type = 'Subscription'. $filter=$filter=resourceType+eq+'subscription'+or+resourceType+eq+'resourcegroup''
List resources of type = 'Subscription' or type = 'ResourceGroup'. Use the
id
of any child resource to use as thescope
for the activationRoleAssignmentScheduleRequest
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 : RoleAssignmentExistsmessage : The Role assignment already exists. |
A similar role assignment already exists | You can GET this role assignment and verify its schedule. |
code : RoleAssignmentRequestPolicyValidationFailedmessage : 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 : RoleAssignmentRequestPolicyValidationFailedmessage : 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 : RoleAssignmentRequestPolicyValidationFailedmessage : 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 : RoleAssignmentRequestPolicyValidationFailedmessage : 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 : RoleAssignmentRequestPolicyValidationFailedmessage : 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 |