Remove-AzRoleDefinition
Deletes a custom role in Azure RBAC. The role to be deleted is specified using the Id property of the role. Delete will fail if there are existing role assignments made to the custom role.
Syntax
RoleDefinitionIdParameterSet (Default)
Remove-AzRoleDefinition
-Id <Guid>
[-Scope <String>]
[-SkipClientSideScopeValidation]
[-Force]
[-PassThru]
[-DefaultProfile <IAzureContextContainer>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
RoleDefinitionNameParameterSet
Remove-AzRoleDefinition
[-Name] <String>
[-Scope <String>]
[-SkipClientSideScopeValidation]
[-Force]
[-PassThru]
[-DefaultProfile <IAzureContextContainer>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
InputObjectParameterSet
Remove-AzRoleDefinition
-InputObject <PSRoleDefinition>
[-SkipClientSideScopeValidation]
[-Force]
[-PassThru]
[-DefaultProfile <IAzureContextContainer>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Description
The Remove-AzRoleDefinition cmdlet deletes a custom role in Azure Role-Based Access Control. Provide the Id parameter of an existing custom role to delete that custom role. By default, Remove-AzRoleDefinition prompts you for confirmation. To suppress the prompt, use the Force parameter. If there are existing role assignments made to the custom role to be deleted, the delete will fail.
When using the -PassThru parameter, the cmdlet returns the deleted PSRoleDefinition object. The returned object contains a Permissions collection with Actions, NotActions, DataActions, NotDataActions, and any Attribute-Based Access Control (ABAC) conditions (Condition and ConditionVersion) for each permission entry.
Examples
Example 1: Remove a custom role by piping from Get-AzRoleDefinition
Get-AzRoleDefinition -Name "Virtual Machine Operator" | Remove-AzRoleDefinition
Retrieves the "Virtual Machine Operator" custom role and pipes it to Remove-AzRoleDefinition for deletion. You will be prompted for confirmation before the role is deleted.
Example 2: Remove a custom role by Id
Remove-AzRoleDefinition -Id "00001111-aaaa-2222-bbbb-3333cccc4444"
Deletes the custom role with the specified Id. You will be prompted for confirmation.
Example 3: Remove a custom role without confirmation
Remove-AzRoleDefinition -Name "Custom Reader Role" -Force
Deletes the custom role named "Custom Reader Role" without prompting for confirmation.
Example 4: Remove and return the deleted role definition
$deletedRole = Remove-AzRoleDefinition -Name "Custom Writer Role" -Force -PassThru
$deletedRole.Permissions[0].Actions
Deletes the role and returns the PSRoleDefinition object, then displays the actions from the first permission entry.
Parameters
-Confirm
Prompts you for confirmation before running the cmdlet.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | cf |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-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 |
-Force
If set, does not prompt for a confirmation before deleting the custom role
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 |
-Id
Id of the Role definition to be deleted
Parameter properties
| Type: | Guid |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
RoleDefinitionIdParameterSet
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-InputObject
The object representing the role definition to be removed.
Parameter properties
| Type: | PSRoleDefinition |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
InputObjectParameterSet
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | True |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Name
Name of the Role definition to be deleted.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
RoleDefinitionNameParameterSet
| Position: | 0 |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-PassThru
The Remove-AzRoleDefinition cmdlet deletes a custom role in Azure Role-Based Access Control. Provide the Id parameter of an existing custom role to delete that custom role. By default, Remove-AzRoleDefinition prompts you for confirmation. To suppress the prompt, use the Force parameter. If there are existing role assignments made to the custom role to be deleted, the delete will fail.
When using the -PassThru parameter, the cmdlet returns the deleted PSRoleDefinition object. The returned object contains a Permissions collection with Actions, NotActions, DataActions, NotDataActions, and any Attribute-Based Access Control (ABAC) conditions (Condition and ConditionVersion) for each permission entry.
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 |
-Scope
Role definition scope.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
RoleDefinitionIdParameterSet
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
RoleDefinitionNameParameterSet
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | True |
| 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 |
-WhatIf
The Remove-AzRoleDefinition cmdlet deletes a custom role in Azure Role-Based Access Control. Provide the Id parameter of an existing custom role to delete that custom role. By default, Remove-AzRoleDefinition prompts you for confirmation. To suppress the prompt, use the Force parameter. If there are existing role assignments made to the custom role to be deleted, the delete will fail.
When using the -PassThru parameter, the cmdlet returns the deleted PSRoleDefinition object. The returned object contains a Permissions collection with Actions, NotActions, DataActions, NotDataActions, and any Attribute-Based Access Control (ABAC) conditions (Condition and ConditionVersion) for each permission entry.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | wi |
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
Guid
String
PSRoleDefinition
Outputs
Boolean
Notes
Keywords: azure, azurerm, arm, resource, management, manager, resource, group, template, deployment
