Add or remove role assignments using Azure RBAC and the REST API

Azure role-based access control (RBAC) is the authorization system you use to manage access to Azure resources. To grant access, you assign roles to users, groups, service principals, or managed identities at a particular scope. This article describes how to assign roles using the REST API.

Prerequisites

To add or remove role assignments, you must have:

  • Microsoft.Authorization/roleAssignments/write and Microsoft.Authorization/roleAssignments/delete permissions, such as User Access Administrator or Owner

Add a role assignment

In RBAC, to grant access, you add a role assignment. To add 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": "/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}",
        "principalId": "{principalId}"
      }
    }
    
  4. Within the URI, replace {scope} with the scope for the role assignment.

    Scope Type
    providers/Microsoft.Management/managementGroups/{groupId1} Management group
    subscriptions/{subscriptionId1} Subscription
    subscriptions/{subscriptionId1}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId1}/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 {scope} with the scope for the role assignment.

    Scope Type
    providers/Microsoft.Management/managementGroups/{groupId1} Management group
    subscriptions/{subscriptionId1} Subscription
    subscriptions/{subscriptionId1}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId1}/resourceGroups/myresourcegroup1/ providers/microsoft.web/sites/mysite1 Resource
  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 a role assignment

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
    providers/Microsoft.Management/managementGroups/{groupId1} Management group
    subscriptions/{subscriptionId1} Subscription
    subscriptions/{subscriptionId1}/resourceGroups/myresourcegroup1 Resource group
    subscriptions/{subscriptionId1}/resourceGroups/myresourcegroup1/ providers/microsoft.web/sites/mysite1 Resource
  4. Replace {roleAssignmentName} with the GUID identifier of the role assignment.

Next steps