Remove-AzRoleDefinition

Module:

Az.Resources Module

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]
    [-AcquirePolicyToken]
    [-ChangeReference <String>]
    [<CommonParameters>]

RoleDefinitionNameParameterSet

Remove-AzRoleDefinition
    [-Name] <String>
    [-Scope <String>]
    [-SkipClientSideScopeValidation]
    [-Force]
    [-PassThru]
    [-DefaultProfile <IAzureContextContainer>]
    [-WhatIf]
    [-Confirm]
    [-AcquirePolicyToken]
    [-ChangeReference <String>]
    [<CommonParameters>]

InputObjectParameterSet

Remove-AzRoleDefinition
    -InputObject <PSRoleDefinition>
    [-SkipClientSideScopeValidation]
    [-Force]
    [-PassThru]
    [-DefaultProfile <IAzureContextContainer>]
    [-WhatIf]
    [-Confirm]
    [-AcquirePolicyToken]
    [-ChangeReference <String>]
    [<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

-AcquirePolicyToken

Acquire an Azure Policy token automatically for this resource operation.

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

-ChangeReference

The change reference resource ID for this resource operation.

Parameter properties

Type:	String
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

-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

Related Links

• New-AzRoleDefinition
• Get-AzRoleDefinition
• Set-AzRoleDefinition