Share via

Use Azure PIM to manage active access with the REST API

  • Article

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.

  1. 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}

  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 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.

  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/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
      }
    }
  }
}

  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 {roleAssignmentScheduleRequestName} 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 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.

  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/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?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 {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.

  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. [Optional] Choose a RoleEligibilitySchedule that you want to activate and get the RoleEligibilityScheduleId from the Role Eligibility Schedules API to pass in as the LinkedRoleEligibilityScheduleId. This is optional, and if not passed the system will pick a RoleEligibilitySchedule.

  3. 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
   }
 }

  4. 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

  5. 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.

  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/roleAssignmentScheduleRequests/{roleAssignmentScheduleRequestName}?api-version=2020-10-01

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

  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 {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.

  1. Start with the following request:

    GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/eligibleChildResources?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

  3. 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'.

  4. Use the id of any child resource to use as the scope for the activation RoleAssignmentScheduleRequest

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