Create or update Azure custom roles using Azure PowerShell
If the Azure built-in roles don't meet the specific needs of your organization, you can create your own custom roles. This article describes how to list, create, update, or delete custom roles using Azure PowerShell.
For a step-by-step tutorial on how to create a custom role, see Tutorial: Create an Azure custom role using Azure PowerShell.
Note
We recommend that you use the Azure Az PowerShell module to interact with Azure. To get started, see Install Azure PowerShell. To learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.
Prerequisites
To create custom roles, you need:
- Permissions to create custom roles, such as User Access Administrator
- Azure Cloud Shell or Azure PowerShell
List custom roles
To list the roles that are available for assignment at a scope, use the Get-AzRoleDefinition command. The following example lists all roles that are available for assignment in the selected subscription.
Get-AzRoleDefinition | FT Name, IsCustom
Name IsCustom
---- --------
Virtual Machine Operator True
AcrImageSigner False
AcrQuarantineReader False
AcrQuarantineWriter False
API Management Service Contributor False
...
The following example lists just the custom roles that are available for assignment in the selected subscription.
Get-AzRoleDefinition -Custom | FT Name, IsCustom
Name IsCustom
---- --------
Virtual Machine Operator True
If the selected subscription isn't in the AssignableScopes of the role, the custom role won't be listed.
List a custom role definition
To list a custom role definition, use Get-AzRoleDefinition. This is the same command as you use for a built-in role.
Get-AzRoleDefinition <role_name> | ConvertTo-Json
PS C:\> Get-AzRoleDefinition "Virtual Machine Operator" | ConvertTo-Json
{
"Name": "Virtual Machine Operator",
"Id": "00000000-0000-0000-0000-000000000000",
"IsCustom": true,
"Description": "Can monitor and restart virtual machines.",
"Actions": [
"Microsoft.Storage/*/read",
"Microsoft.Network/*/read",
"Microsoft.Compute/*/read",
"Microsoft.Compute/virtualMachines/start/action",
"Microsoft.Compute/virtualMachines/restart/action",
"Microsoft.Authorization/*/read",
"Microsoft.ResourceHealth/availabilityStatuses/read",
"Microsoft.Resources/subscriptions/resourceGroups/read",
"Microsoft.Insights/alertRules/*",
"Microsoft.Support/*"
],
"NotActions": [],
"DataActions": [],
"NotDataActions": [],
"AssignableScopes": [
"/subscriptions/11111111-1111-1111-1111-111111111111"
]
}
The following example lists just the actions of the role:
(Get-AzRoleDefinition <role_name>).Actions
PS C:\> (Get-AzRoleDefinition "Virtual Machine Operator").Actions
"Microsoft.Storage/*/read",
"Microsoft.Network/*/read",
"Microsoft.Compute/*/read",
"Microsoft.Compute/virtualMachines/start/action",
"Microsoft.Compute/virtualMachines/restart/action",
"Microsoft.Authorization/*/read",
"Microsoft.ResourceHealth/availabilityStatuses/read",
"Microsoft.Resources/subscriptions/resourceGroups/read",
"Microsoft.Insights/alertRules/*",
"Microsoft.Insights/diagnosticSettings/*",
"Microsoft.Support/*"
Create a custom role
To create a custom role, use the New-AzRoleDefinition command. There are two methods of structuring the role, using PSRoleDefinition object or a JSON template.
Get operations for a resource provider
When you create custom roles, it is important to know all the possible operations from the resource providers. You can view the list of resource provider operations or you can use the Get-AzProviderOperation command to get this information. For example, if you want to check all the available operations for virtual machines, use this command:
Get-AzProviderOperation <operation> | FT OperationName, Operation, Description -AutoSize
PS C:\> Get-AzProviderOperation "Microsoft.Compute/virtualMachines/*" | FT OperationName, Operation, Description -AutoSize
OperationName Operation Description
------------- --------- -----------
Get Virtual Machine Microsoft.Compute/virtualMachines/read Get the propertie...
Create or Update Virtual Machine Microsoft.Compute/virtualMachines/write Creates a new vir...
Delete Virtual Machine Microsoft.Compute/virtualMachines/delete Deletes the virtu...
Start Virtual Machine Microsoft.Compute/virtualMachines/start/action Starts the virtua...
...
Create a custom role with the PSRoleDefinition object
When you use PowerShell to create a custom role, you can use one of the built-in roles as a starting point or you can start from scratch. The first example in this section starts with a built-in role and then customizes it with more permissions. Edit the attributes to add the Actions, NotActions, or AssignableScopes that you want, and then save the changes as a new role.
The following example starts with the Virtual Machine Contributor built-in role to create a custom role named Virtual Machine Operator. The new role grants access to all read actions of Microsoft.Compute, Microsoft.Storage, and Microsoft.Network resource providers and grants access to start, restart, and monitor virtual machines. The custom role can be used in two subscriptions.
$role = Get-AzRoleDefinition "Virtual Machine Contributor"
$role.Id = $null
$role.Name = "Virtual Machine Operator"
$role.Description = "Can monitor and restart virtual machines."
$role.Actions.Clear()
$role.Actions.Add("Microsoft.Storage/*/read")
$role.Actions.Add("Microsoft.Network/*/read")
$role.Actions.Add("Microsoft.Compute/*/read")
$role.Actions.Add("Microsoft.Compute/virtualMachines/start/action")
$role.Actions.Add("Microsoft.Compute/virtualMachines/restart/action")
$role.Actions.Add("Microsoft.Authorization/*/read")
$role.Actions.Add("Microsoft.ResourceHealth/availabilityStatuses/read")
$role.Actions.Add("Microsoft.Resources/subscriptions/resourceGroups/read")
$role.Actions.Add("Microsoft.Insights/alertRules/*")
$role.Actions.Add("Microsoft.Support/*")
$role.AssignableScopes.Clear()
$role.AssignableScopes.Add("/subscriptions/00000000-0000-0000-0000-000000000000")
$role.AssignableScopes.Add("/subscriptions/11111111-1111-1111-1111-111111111111")
New-AzRoleDefinition -Role $role
The following example shows another way to create the Virtual Machine Operator custom role. It starts by creating a new PSRoleDefinition object. The actions are specified in the perms variable and set to the Actions property. The NotActions property is set by reading the NotActions from the Virtual Machine Contributor built-in role. Since Virtual Machine Contributor does not have any NotActions, this line is not required, but it shows how information can be retrieved from another role.
$role = [Microsoft.Azure.Commands.Resources.Models.Authorization.PSRoleDefinition]::new()
$role.Name = 'Virtual Machine Operator 2'
$role.Description = 'Can monitor and restart virtual machines.'
$role.IsCustom = $true
$perms = 'Microsoft.Storage/*/read','Microsoft.Network/*/read','Microsoft.Compute/*/read'
$perms += 'Microsoft.Compute/virtualMachines/start/action','Microsoft.Compute/virtualMachines/restart/action'
$perms += 'Microsoft.Authorization/*/read'
$perms += 'Microsoft.ResourceHealth/availabilityStatuses/read'
$perms += 'Microsoft.Resources/subscriptions/resourceGroups/read'
$perms += 'Microsoft.Insights/alertRules/*','Microsoft.Support/*'
$role.Actions = $perms
$role.NotActions = (Get-AzRoleDefinition -Name 'Virtual Machine Contributor').NotActions
$subs = '/subscriptions/00000000-0000-0000-0000-000000000000','/subscriptions/11111111-1111-1111-1111-111111111111'
$role.AssignableScopes = $subs
New-AzRoleDefinition -Role $role
Create a custom role with JSON template
A JSON template can be used as the source definition for the custom role. The following example creates a custom role that allows read access to storage and compute resources, access to support, and adds that role to two subscriptions. Create a new file C:\CustomRoles\customrole1.json with the following example. The Id should be set to null on initial role creation as a new ID is generated automatically.
{
"Name": "Custom Role 1",
"Id": null,
"IsCustom": true,
"Description": "Allows for read access to Azure storage and compute resources and access to support",
"Actions": [
"Microsoft.Compute/*/read",
"Microsoft.Storage/*/read",
"Microsoft.Support/*"
],
"NotActions": [],
"AssignableScopes": [
"/subscriptions/00000000-0000-0000-0000-000000000000",
"/subscriptions/11111111-1111-1111-1111-111111111111"
]
}
To add the role to the subscriptions, run the following PowerShell command:
New-AzRoleDefinition -InputFile "C:\CustomRoles\customrole1.json"
Update a custom role
Similar to creating a custom role, you can modify an existing custom role using either the PSRoleDefinition object or a JSON template.
Update a custom role with the PSRoleDefinition object
To modify a custom role, first, use the Get-AzRoleDefinition command to retrieve the role definition. Second, make the desired changes to the role definition. Finally, use the Set-AzRoleDefinition command to save the modified role definition.
The following example adds the Microsoft.Insights/diagnosticSettings/* action to the Virtual Machine Operator custom role.
$role = Get-AzRoleDefinition "Virtual Machine Operator"
$role.Actions.Add("Microsoft.Insights/diagnosticSettings/*")
Set-AzRoleDefinition -Role $role
PS C:\> $role = Get-AzRoleDefinition "Virtual Machine Operator"
PS C:\> $role.Actions.Add("Microsoft.Insights/diagnosticSettings/*")
PS C:\> Set-AzRoleDefinition -Role $role
Name : Virtual Machine Operator
Id : 88888888-8888-8888-8888-888888888888
IsCustom : True
Description : Can monitor and restart virtual machines.
Actions : {Microsoft.Storage/*/read, Microsoft.Network/*/read, Microsoft.Compute/*/read,
Microsoft.Compute/virtualMachines/start/action...}
NotActions : {}
AssignableScopes : {/subscriptions/00000000-0000-0000-0000-000000000000,
/subscriptions/11111111-1111-1111-1111-111111111111}
The following example adds an Azure subscription to the assignable scopes of the Virtual Machine Operator custom role.
Get-AzSubscription -SubscriptionName Production3
$role = Get-AzRoleDefinition "Virtual Machine Operator"
$role.AssignableScopes.Add("/subscriptions/22222222-2222-2222-2222-222222222222")
Set-AzRoleDefinition -Role $role
PS C:\> Get-AzSubscription -SubscriptionName Production3
Name : Production3
Id : 22222222-2222-2222-2222-222222222222
TenantId : 99999999-9999-9999-9999-999999999999
State : Enabled
PS C:\> $role = Get-AzRoleDefinition "Virtual Machine Operator"
PS C:\> $role.AssignableScopes.Add("/subscriptions/22222222-2222-2222-2222-222222222222")
PS C:\> Set-AzRoleDefinition -Role $role
Name : Virtual Machine Operator
Id : 88888888-8888-8888-8888-888888888888
IsCustom : True
Description : Can monitor and restart virtual machines.
Actions : {Microsoft.Storage/*/read, Microsoft.Network/*/read, Microsoft.Compute/*/read,
Microsoft.Compute/virtualMachines/start/action...}
NotActions : {}
AssignableScopes : {/subscriptions/00000000-0000-0000-0000-000000000000,
/subscriptions/11111111-1111-1111-1111-111111111111,
/subscriptions/22222222-2222-2222-2222-222222222222}
The following example adds a management group to AssignableScopes of the Virtual Machine Operator custom role.
Get-AzManagementGroup
$role = Get-AzRoleDefinition "Virtual Machine Operator"
$role.AssignableScopes.Add("/providers/Microsoft.Management/managementGroups/{groupId1}")
Set-AzRoleDefinition -Role $role
PS C:\> Get-AzManagementGroup
Id : /providers/Microsoft.Management/managementGroups/marketing-group
Type : /providers/Microsoft.Management/managementGroups
Name : marketing-group
TenantId : 99999999-9999-9999-9999-999999999999
DisplayName : Marketing group
PS C:\> $role = Get-AzRoleDefinition "Virtual Machine Operator"
PS C:\> $role.AssignableScopes.Add("/providers/Microsoft.Management/managementGroups/marketing-group")
PS C:\> Set-AzRoleDefinition -Role $role
Name : Virtual Machine Operator
Id : 88888888-8888-8888-8888-888888888888
IsCustom : True
Description : Can monitor and restart virtual machines.
Actions : {Microsoft.Storage/*/read, Microsoft.Network/*/read, Microsoft.Compute/*/read,
Microsoft.Compute/virtualMachines/start/action...}
NotActions : {}
AssignableScopes : {/subscriptions/00000000-0000-0000-0000-000000000000,
/subscriptions/11111111-1111-1111-1111-111111111111,
/subscriptions/22222222-2222-2222-2222-222222222222,
/providers/Microsoft.Management/managementGroups/marketing-group}
Update a custom role with a JSON template
Using the previous JSON template, you can easily modify an existing custom role to add or remove Actions. Update the JSON template and add the read action for networking as shown in the following example. The definitions listed in the template are not cumulatively applied to an existing definition, meaning that the role appears exactly as you specify in the template. You also need to update the Id field with the ID of the role. If you aren't sure what this value is, you can use the Get-AzRoleDefinition cmdlet to get this information.
{
"Name": "Custom Role 1",
"Id": "acce7ded-2559-449d-bcd5-e9604e50bad1",
"IsCustom": true,
"Description": "Allows for read access to Azure storage and compute resources and access to support",
"Actions": [
"Microsoft.Compute/*/read",
"Microsoft.Storage/*/read",
"Microsoft.Network/*/read",
"Microsoft.Support/*"
],
"NotActions": [],
"AssignableScopes": [
"/subscriptions/00000000-0000-0000-0000-000000000000",
"/subscriptions/11111111-1111-1111-1111-111111111111"
]
}
To update the existing role, run the following PowerShell command:
Set-AzRoleDefinition -InputFile "C:\CustomRoles\customrole1.json"
Delete a custom role
Remove any role assignments that use the custom role. For more information, see Find role assignments to delete a custom role.
Use the Remove-AzRoleDefinition command to delete the custom role.
The following example removes the Virtual Machine Operator custom role.
Get-AzRoleDefinition "Virtual Machine Operator" Get-AzRoleDefinition "Virtual Machine Operator" | Remove-AzRoleDefinitionPS C:\> Get-AzRoleDefinition "Virtual Machine Operator" Name : Virtual Machine Operator Id : 88888888-8888-8888-8888-888888888888 IsCustom : True Description : Can monitor and restart virtual machines. Actions : {Microsoft.Storage/*/read, Microsoft.Network/*/read, Microsoft.Compute/*/read, Microsoft.Compute/virtualMachines/start/action...} NotActions : {} AssignableScopes : {/subscriptions/00000000-0000-0000-0000-000000000000, /subscriptions/11111111-1111-1111-1111-111111111111} PS C:\> Get-AzRoleDefinition "Virtual Machine Operator" | Remove-AzRoleDefinition Confirm Are you sure you want to remove role definition with name 'Virtual Machine Operator'. [Y] Yes [N] No [S] Suspend [?] Help (default is "Y"): Y