Use RBAC to manage access with the REST API

Role-based access control (RBAC) helps you manage access to Azure resources. For example, you can allow a user to manage the virtual machines in a particular resource group. You manage access for users, groups, and service principals (applications) by assigning roles at a particular scope. You can manage access using the Azure portal, Azure PowerShell, Azure CLI, Azure SDKs, or REST API. This article describes the common ways to manage access using the REST API.

List access

To list role assignments (list access), you can use one of the Role Assignments - List 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.

  1. Start with the following request:

    GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignments?api-version=2015-07-01&$filter={filter}

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

    Scope Type
    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=assignedTo('{objectId}') List role assignments for a specified user, including ones inherited from groups.

Grant access

To create a role assignment (grant access), you use the Role Assignments - Create REST API and specify the security principal, role definition, 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/roleAssignments/{roleAssignmentName}?api-version=2015-07-01

    {
  "properties": {
    "roleDefinitionId": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
    "principalId": "{principalId}"
  }
}

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

    Scope Type
    subscriptions/{subscriptionId} Subscription
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1 Resource

  5. Replace {roleAssignmentName} 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 access

To remove a role assignment (remove access), use the Role Assignments - Delete REST API. To call this API, you must have access to the Microsoft.Authorization/roleAssignments/delete operation. Of the built-in roles, only Owner and User Access Administrator are granted access to this operation.

  1. Get the role assignment identifier (GUID). This identifier is returned when you first create the role assignment or you can get it by listing the role assignments.

  2. Start with the following request:

    DELETE https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleAssignments/{roleAssignmentName}?api-version=2015-07-01

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

    Scope Type
    subscriptions/{subscriptionId} Subscription
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId}/resourceGroups/myresourcegroup1/ providers/Microsoft.Web/sites/mysite1 Resource

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

Next steps

  • Last updated on