Quickstart: Assign an Azure role using an ARM template

Azure role-based access control (Azure RBAC) is the way that you manage access to Azure resources. In this quickstart, you create a resource group and grant a user access to create and manage virtual machines in the resource group. This quickstart uses an Azure Resource Manager template (ARM template) to grant the access.

A resource manager template is a JavaScript Object Notation (JSON) file that defines the infrastructure and configuration for your project. The template uses declarative syntax. In declarative syntax, you describe your intended deployment without writing the sequence of programming commands to create the deployment.

If your environment meets the prerequisites and you're familiar with using ARM templates, select the Deploy to Azure button. The template will open in the Azure portal.

Deploy to Azure


To assign Azure roles and remove role assignments, you must have:

  • If you don't have an Azure subscription, create a free account before you begin.
  • Microsoft.Authorization/roleAssignments/write and Microsoft.Authorization/roleAssignments/delete permissions, such as User Access Administrator or Owner
  • To assign a role, you must specify three elements: security principal, role definition, and scope. For this quickstart, the security principal is you or another user in your directory, the role definition is Virtual Machine Contributor, and the scope is a resource group that you specify.

Review the template

The template used in this quickstart is from Azure Quickstart Templates. The template has two parameters and a resources section. In the resources section, notice that it has the three elements of a role assignment: security principal, role definition, and scope.

  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "",
  "metadata": {
    "_generator": {
      "name": "bicep",
      "version": "",
      "templateHash": "15014882513681156573"
  "parameters": {
    "roleDefinitionID": {
      "type": "string",
      "metadata": {
        "description": "Specifies the role definition ID used in the role assignment."
    "principalId": {
      "type": "string",
      "metadata": {
        "description": "Specifies the principal ID assigned to the role."
  "variables": {
    "roleAssignmentName": "[guid(parameters('principalId'), parameters('roleDefinitionID'), resourceGroup().id)]"
  "resources": [
      "type": "Microsoft.Authorization/roleAssignments",
      "apiVersion": "2021-04-01-preview",
      "name": "[variables('roleAssignmentName')]",
      "properties": {
        "roleDefinitionId": "[resourceId('Microsoft.Authorization/roleDefinitions', parameters('roleDefinitionID'))]",
        "principalId": "[parameters('principalId')]"

The resource defined in the template is:

Deploy the template

  1. Sign in to the Azure portal.

  2. Determine your email address that is associated with your Azure subscription. Or determine the email address of another user in your directory.

  3. Open Azure Cloud Shell for PowerShell.

  4. Copy and paste the following script into Cloud Shell.

    $resourceGroupName = Read-Host -Prompt "Enter a resource group name (i.e. ExampleGrouprg)"
    $emailAddress = Read-Host -Prompt "Enter an email address for a user in your directory"
    $location = Read-Host -Prompt "Enter a location (i.e. centralus)"
    $roleAssignmentName = New-Guid
    $principalId = (Get-AzAdUser -Mail $emailAddress).id
    $roleDefinitionId = (Get-AzRoleDefinition -name "Virtual Machine Contributor").id
    $templateUri = "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.authorization/rbac-builtinrole-resourcegroup/azuredeploy.json"
    New-AzResourceGroup -Name $resourceGroupName -Location $location
    New-AzResourceGroupDeployment -ResourceGroupName $resourceGroupName -TemplateUri $templateUri -roleDefinitionID $roleDefinitionId -principalId $principalId
  5. Enter a resource group name such as ExampleGrouprg.

  6. Enter an email address for yourself or another user in your directory.

  7. Enter a location for the resource group such as centralus.

  8. If necessary, press Enter to run the New-AzResourceGroupDeployment command.

    The New-AzResourceGroup command creates a new resource group and the New-AzResourceGroupDeployment command deploys the template to add the role assignment.

    You should see output similar to the following:

    PS> New-AzResourceGroupDeployment -ResourceGroupName $resourceGroupName -TemplateUri $templateUri -roleAssignmentName $roleAssignmentName -roleDefinitionID $roleDefinitionId -principalId $principalId
    DeploymentName          : azuredeploy
    ResourceGroupName       : ExampleGrouprg
    ProvisioningState       : Succeeded
    Timestamp               : 5/22/2020 9:01:30 PM
    Mode                    : Incremental
    TemplateLink            :
                              Uri            : https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.authorization/rbac-builtinrole-resourcegroup/azuredeploy.json
                              ContentVersion :
    Parameters              :
                              Name                  Type                       Value
                              ====================  =========================  ==========
                              roleDefinitionID      String                     9980e02c-c2be-4d73-94e8-173b1dc7cf3c
                              principalId           String                     {principalId}
    Outputs                 :
    DeploymentDebugLogLevel :

Review deployed resources

  1. In the Azure portal, open the resource group you created.

  2. In the left menu, click Access control (IAM).

  3. Click the Role assignments tab.

  4. Verify that the Virtual Machine Contributor role is assigned to the user you specified.

    New role assignment

Clean up resources

To remove the role assignment and resource group you created, follow these steps.

  1. Copy and paste the following script into Cloud Shell.

    $emailAddress = Read-Host -Prompt "Enter the email address of the user with the role assignment to remove"
    $resourceGroupName = Read-Host -Prompt "Enter the resource group name to remove (i.e. ExampleGrouprg)"
    $principalId = (Get-AzAdUser -Mail $emailAddress).id
    Remove-AzRoleAssignment -ObjectId $principalId -RoleDefinitionName "Virtual Machine Contributor" -ResourceGroupName $resourceGroupName
    Remove-AzResourceGroup -Name $resourceGroupName
  2. Enter the email address of the user with the role assignment to remove.

  3. Enter the resource group name to remove such as ExampleGrouprg.

  4. If necessary, press Enter to run the Remove-AzResourceGroup command.

  5. Enter Y to confirm that you want to remove the resource group.

Next steps