Create or update Azure custom roles using Azure PowerShell - Azure RBAC (2023)

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.

Prerequisites

To create custom roles, you need:

• Permissions to create custom roles, such as Owner or 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 TrueAcrImageSigner FalseAcrQuarantineReader FalseAcrQuarantineWriter FalseAPI 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 -AutoSizeOperationName 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 = $subsNew-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 $roleName : Virtual Machine OperatorId : 88888888-8888-8888-8888-888888888888IsCustom : TrueDescription : 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 Production3Name : Production3Id : 22222222-2222-2222-2222-222222222222TenantId : 99999999-9999-9999-9999-999999999999State : EnabledPS C:\> $role = Get-AzRoleDefinition "Virtual Machine Operator"PS C:\> $role.AssignableScopes.Add("/subscriptions/22222222-2222-2222-2222-222222222222")PS C:\> Set-AzRoleDefinition -Role $roleName : Virtual Machine OperatorId : 88888888-8888-8888-8888-888888888888IsCustom : TrueDescription : 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. Adding a management group to AssignableScopes is currently in preview.

Get-AzManagementGroup$role = Get-AzRoleDefinition "Virtual Machine Operator"$role.AssignableScopes.Add("/providers/Microsoft.Management/managementGroups/{groupId1}")Set-AzRoleDefinition -Role $role

PS C:\> Get-AzManagementGroupId : /providers/Microsoft.Management/managementGroups/marketing-groupType : /providers/Microsoft.Management/managementGroupsName : marketing-groupTenantId : 99999999-9999-9999-9999-999999999999DisplayName : Marketing groupPS C:\> $role = Get-AzRoleDefinition "Virtual Machine Operator"PS C:\> $role.AssignableScopes.Add("/providers/Microsoft.Management/managementGroups/marketing-group")PS C:\> Set-AzRoleDefinition -Role $roleName : Virtual Machine OperatorId : 88888888-8888-8888-8888-888888888888IsCustom : TrueDescription : 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

1. Remove any role assignments that use the custom role. For more information, see Find role assignments to delete a custom role.

2. 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-AzRoleDefinition

   PS C:\> Get-AzRoleDefinition "Virtual Machine Operator"Name : Virtual Machine OperatorId : 88888888-8888-8888-8888-888888888888IsCustom : TrueDescription : 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-AzRoleDefinitionConfirmAre you sure you want to remove role definition with name 'Virtual Machine Operator'.[Y] Yes [N] No [S] Suspend [?] Help (default is "Y"): Y

Next steps

• Tutorial: Create an Azure custom role using Azure PowerShell
• Azure custom roles
• Azure resource provider operations