Quickstart: Assign an Azure role using an ARM template

Article
12/01/2023

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.

An Azure Resource Manager template is a JavaScript Object Notation (JSON) file that defines the infrastructure and configuration for your project. The template uses 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.

Prerequisites

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 Role Based Access Control Administrator
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": "1.0.0.0",
  "metadata": {
    "_generator": {
      "name": "bicep",
      "version": "0.25.53.49325",
      "templateHash": "15160858749942476090"
    }
  },
  "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": "2022-04-01",
      "name": "[variables('roleAssignmentName')]",
      "properties": {
        "roleDefinitionId": "[resourceId('Microsoft.Authorization/roleDefinitions', parameters('roleDefinitionID'))]",
        "principalId": "[parameters('principalId')]"
      }
    }
  ],
  "outputs": {
    "name": {
      "type": "string",
      "value": "[variables('roleAssignmentName')]"
    },
    "resourceGroupName": {
      "type": "string",
      "value": "[resourceGroup().name]"
    },
    "resourceId": {
      "type": "string",
      "value": "[resourceId('Microsoft.Authorization/roleAssignments', variables('roleAssignmentName'))]"
    }
  }
}

The resource defined in the template is:

Microsoft.Authorization/roleAssignments

Deploy the template

Sign in to the Azure portal.
Determine your email address that is associated with your Azure subscription. Or determine the email address of another user in your directory.
Open Azure Cloud Shell for PowerShell.

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

Enter a resource group name such as ExampleGrouprg.
Enter an email address for yourself or another user in your directory.
Enter a location for the resource group such as centralus.

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 : 1.0.0.0

Parameters              :
                          Name                  Type                       Value
                          ====================  =========================  ==========
                          roleDefinitionID      String                     9980e02c-c2be-4d73-94e8-173b1dc7cf3c
                          principalId           String                     {principalId}

Outputs                 :
DeploymentDebugLogLevel :

Review deployed resources

In the Azure portal, open the resource group you created.
In the left menu, click Access control (IAM).
Click the Role assignments tab.
Verify that the Virtual Machine Contributor role is assigned to the user you specified.

Clean up resources

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

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

Enter the email address of the user with the role assignment to remove.
Enter the resource group name to remove such as ExampleGrouprg.
If necessary, press Enter to run the Remove-AzResourceGroup command.
Enter Y to confirm that you want to remove the resource group.

Next steps

Tutorial: Grant a user access to Azure resources using Azure PowerShell