Manage access to Azure resources using RBAC and the REST API

Role-based access control (RBAC) is the way that you manage access to Azure resources. 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.

  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

    Note

    In the above example Microsoft.web is the resource provider is used which refers to App service instance. Similarly you can use any other resource provider and build the Scope URI. In order to understand more please refer to Azure Resource providers and types and supported Azure RM resource provider operations.

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

    Filter Description
    $filter=atScope() Lists role assignments for only the specified scope, not including the role assignments at subscopes.
    $filter=principalId%20eq%20'{objectId}' Lists role assignments for a specified user, group, or service principal.
    $filter=assignedTo('{objectId}') Lists role assignments for a specified user or service principal. If the user is a member of a group that has a role assignment, that role assignment is also listed. This filter is transitive for groups which means that if the user is a member of a group and that group is a member of another group that has a role assignment, that role assignment is also listed. This filter only accepts an object id for a user or a service principal. You cannot pass an object id for a group.

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