Set-AzRoleDefinition
Modifies a custom role in Azure RBAC. Provide the modified role definition either as a JSON file or as a PSRoleDefinition. First, use the Get-AzRoleDefinition command to retrieve the custom role that you wish to modify. Then, modify the properties that you wish to change. Finally, save the role definition using this command.
Syntax
InputFileParameterSet
Set-AzRoleDefinition
-InputFile <String>
[-SkipClientSideScopeValidation]
[-DefaultProfile <IAzureContextContainer>]
[<CommonParameters>]
RoleDefinitionParameterSet
Set-AzRoleDefinition
-Role <PSRoleDefinition>
[-SkipClientSideScopeValidation]
[-DefaultProfile <IAzureContextContainer>]
[<CommonParameters>]
Description
The Set-AzRoleDefinition cmdlet updates an existing custom role in Azure Role-Based Access Control. Provide the updated role definition as an input to the command as a JSON file or a PSRoleDefinition object.
The role definition for the updated custom role MUST contain:
- Id: the unique identifier of the role definition to update
- Name: the name of the custom role
- Description: a short description of the role
- Permissions: an array of permission objects containing Actions and/or DataActions
- AssignableScopes: the scopes where the role can be assigned
Each permission object in the Permissions array can contain Actions, NotActions, DataActions, NotDataActions, and optionally Condition and ConditionVersion for Attribute-Based Access Control (ABAC) conditions.
Important
The shape of PSRoleDefinition and of the -InputFile JSON has changed. Both -Role (PSRoleDefinition) and -InputFile (JSON) now use a Permissions array of permission objects instead of flattened top-level Actions, NotActions, DataActions, and NotDataActions properties. Scripts that pipe Get-AzRoleDefinition into Set-AzRoleDefinition -Role must read and modify actions and conditions through $role.Permissions[n] rather than directly on the role object. JSON files used with -InputFile must likewise nest permissions under a Permissions array.
Note
The Azure RBAC API currently supports only a single element in the Permissions array when updating custom roles. While the data model supports multiple permission entries, update operations must use exactly one permission object.
Examples
Example 1: Update using PSRoleDefinitionObject
$roleDef = Get-AzRoleDefinition "Contoso On-Call"
$roleDef.Permissions[0].Actions.Add("Microsoft.ClassicCompute/virtualmachines/start/action")
$roleDef.Description = "Can monitor all resources and start and restart virtual machines"
$roleDef.AssignableScopes = @("/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")
Set-AzRoleDefinition -Role $roleDef
Example 2: Update using JSON file
Set-AzRoleDefinition -InputFile C:\Temp\roleDefinition.json
Updates a custom role definition from a JSON file. The JSON file must include the role's Id property.
Parameters
-DefaultProfile
The credentials, account, tenant, and subscription used for communication with azure
Parameter properties
| Type: | IAzureContextContainer |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | AzContext, AzureRmContext, AzureCredential |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-InputFile
File name containing a single json role definition to be updated. Only include the properties that are to be updated in the JSON. Id property is Required.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
InputFileParameterSet
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Role
Role definition object to be updated
Parameter properties
| Type: | PSRoleDefinition |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
RoleDefinitionParameterSet
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | True |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-SkipClientSideScopeValidation
If specified, skip client side scope validation.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
Inputs
PSRoleDefinition
Outputs
PSRoleDefinition
Notes
Keywords: azure, azurerm, arm, resource, management, manager, resource, group, template, deployment
