Manage access using RBAC and the REST API

Role-based access control (RBAC) is the way that you manage access to resources in Azure. This article describes how you manage access for users, groups, and applications using RBAC and the REST API.

List access

In RBAC, to list access, you list the role assignments. To list role assignments, 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. Several 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

In RBAC, to grant access, you create a role assignment. To create a role assignment, 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 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 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

In RBAC, to remove access, you remove a role assignment. To remove a role assignment, 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