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.

Prerequisites

To create custom roles, you need:

• Permissions to create custom roles, such as User Access Administrator
• 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/*"
  ],
  "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/*"

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.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'
$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"
  ],
  "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"
  ],
  "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 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
   

Next steps

• Azure custom roles
• Azure resource provider operations