Create a custom role with Azure role-based access control (Azure RBAC) using PowerShell

• Author
• Recent Posts

Prateek Singh

Prateek Singh is an infrastructure developer, an avid PowerShell blogger, and a community contributor. In 2017, FeedSpot recognized his blog RidiCurious.com as among the "Top 50 PowerShell blogs in the world." All of his PowerShell projects and modules are open-sourced at GitHub, and you can reach out to him on Twitter at @SinghPrateik.

Latest posts by Prateek Singh (see all)

• Create a custom role with Azure role-based access control (Azure RBAC) using PowerShell - Wed, Jan 20 2021
• Step by step Deploying Docker Container to Azure using Azure CLI - Wed, Sep 2 2020
• Install Docker offline on Windows Server 2016 - Thu, Dec 6 2018

Even though Azure offers many built-in roles, it's sometimes necessary to create custom roles with a specific permission to meet a requirement. For example, you may need to remove the "Restart" and "Shutdown" Virtual Machine permissions for a user or an intern so that they don't accidently shut down a production VM. This is exactly the use case where you need custom roles. We will cover this example below and learn to create a custom role and assign it to a user using Azure PowerShell.

First things first. Log in to your Azure account using the command below from a PowerShell Console, assuming that you already have the Azure PowerShell module installed on your system. It will prompt you to provide the email address and password associated with your Azure account. Once submitted, it will sign in your account from PowerShell console.

Login-AzAccount

If you have multiple Azure subscriptions, select the subscription where you want to work using the following commands:

Select-AzSubscription -Subscription "Your Subscription"

Before you can proceed with creating a custom role, let's first quickly understand how to retrieve actions that can be allowed or restricted on a role. You can use the following cmdlet to list all the operations that are applicable on an Azure resource, such as "Virtual Machine," and select the actions that you want to control in a role, such as "Power off / restart Virtual Machine." These are highlighted in the following image.

Get-AzProviderOperation "Microsoft.Compute/virtualMachines/*" | Select-Object Operation*

List allowed operations on an Azure resource.jpg

Create custom role definition

Once you have the names of the operations, such as "Microsoft.Compute/virtualMachines/powerOff/action" and "Microsoft.Compute/virtualMachines/restart/action," then you can use the following JSON template to create a JSON file and mention the operation names under the "Actions" and "NotActions" properties. The "NotActions" property restricts the operation on a role, which is our use case. Be sure to change the value of the "AssignableScopes" property with the Subscription ID of your Azure subscription.

{
 "Name": "Disable VM Shutdown and restart",
 "Id": null,
 "IsCustom": true,
 "Description": "The users of this role can't shut down and restart virtual machines",
 "Actions": [
  "Microsoft.Compute/*/read",
  "Microsoft.Compute/virtualMachines/start/action"
 ],
 "NotActions": [
  "Microsoft.Compute/virtualMachines/powerOff/action",
  "Microsoft.Compute/virtualMachines/restart/action"
 ],
 "AssignableScopes": [
  "/subscriptions/<your subscription id>
 ]
}

After updating your file, save it as "role.json" and use the following cmdlet to create the Custom Role with the definition defined in the JSON file:

New-AzRoleDefinition -InputFile C:\temp\role.json

Create new Azure custom role definition.jpg

Once the custom role definition is created, it can be verified using the following command:

Get-AzRoleDefinition -Custom

Check Azure custom role definition.jpg

Assign a custom role to a user

Now that you have created the Azure custom role definition, you can assign it to a user using the command below. Here you have to mention the sign-in name of the user, name of the role definition, and the resource group where you want to apply this custom role.

$params = @{
  SignInName = "useremail@domain.com"
  RoleDefinitionName = "Disable VM Shutdown and restart"
  ResourceGroupName = "RG"
}

New-AzRoleAssignment @params

Assigning an Azure custom role definition to a user.jpg

After running the command, if you log in to Azure using the above-mentioned Azure account, go to the resource group, and attempt to restart or shut down the virtual machine, you will see an error message in the top right corner, as shown in the following image. This shows that the user is unauthorized to perform these actions on the Azure Virtual Machine, because you didn't allow these actions in your custom role definition.

Testing the Azure custom role definition for a user.jpg

Conclusion

Azure custom roles provide more fine-grained control to customize roles and actions users can perform, compared to the Azure built-in roles. On top of that, Azure PowerShell makes it very simple to automate creating custom roles and keeping your role definitions as JSON files, which can also be treated as Infrastructure-as-Code to track changes in permissions and Azure roles. Once a custom role is created, with just a few Azure PowerShell commands, you can assign the role to users and enforce the custom permissions with ease and simplicity.