Merge pull request #206193 from rolyon/rolyon-rbac-custom-roles-delete

[Azure RBAC] Find role assignments to delete a custom role

Author: PRMerger5

articles/role-based-access-control/custom-roles-cli.md

@@ -11,7 +11,7 @@ ms.service: role-based-access-control
 ms.topic: how-to
 ms.tgt_pltfrm: na
 ms.workload: identity
-ms.date: 06/17/2020
+ms.date: 07/28/2022
 ms.author: rolyon
 ms.reviewer: bagovind
 ---
@@ -222,18 +222,20 @@ az role definition update --role-definition ~/roles/vmoperator.json
 
 ## Delete a custom role
 
-To delete a custom role, use [az role definition delete](/cli/azure/role/definition#az-role-definition-delete). To specify the role to delete, use the role name or the role ID. To determine the role ID, use [az role definition list](/cli/azure/role/definition#az-role-definition-list).
+1. Remove any role assignments that use the custom role. For more information, see [Find role assignments to delete a custom role](custom-roles.md#find-role-assignments-to-delete-a-custom-role).
 
-```azurecli
-az role definition delete --name {roleNameOrId}
-```
-
-The following example deletes the *Virtual Machine Operator* custom role.
-
-```azurecli
-az role definition delete --name "Virtual Machine Operator"
-```
+1. Use [az role definition delete](/cli/azure/role/definition#az-role-definition-delete) to delete the custom role. To specify the role to delete, use the role name or the role ID. To determine the role ID, use [az role definition list](/cli/azure/role/definition#az-role-definition-list).
 
+    ```azurecli
+    az role definition delete --name {roleNameOrId}
+    ```
+    
+    The following example deletes the *Virtual Machine Operator* custom role.
+    
+    ```azurecli
+    az role definition delete --name "Virtual Machine Operator"
+    ```
+    
 ## Next steps
 
 - [Tutorial: Create an Azure custom role using Azure CLI](tutorial-custom-role-cli.md)

articles/role-based-access-control/custom-roles-portal.md

@@ -8,7 +8,7 @@ manager: karenhoran
 ms.service: role-based-access-control
 ms.topic: how-to
 ms.workload: identity
-ms.date: 08/27/2021
+ms.date: 07/28/2022
 ms.author: rolyon
 ---
 
@@ -318,9 +318,9 @@ Follow these steps to view your custom roles.
 
 ## Delete a custom role
 
-1. As described earlier in this article, open your list of custom roles.
+1. Remove any role assignments that use the custom role. For more information, see [Find role assignments to delete a custom role](custom-roles.md#find-role-assignments-to-delete-a-custom-role).
 
-1. Remove any role assignments that using the custom role.
+1. As described earlier in this article, open your list of custom roles.
 
 1. Click the ellipsis (**...**) for the custom role you want to delete and then click **Delete**.
 

articles/role-based-access-control/custom-roles-powershell.md

@@ -11,7 +11,7 @@ ms.service: role-based-access-control
 ms.topic: how-to
 ms.tgt_pltfrm: na
 ms.workload: identity
-ms.date: 03/18/2020
+ms.date: 07/28/2022
 ms.author: rolyon
 ms.reviewer: bagovind 
 ms.custom: devx-track-azurepowershell
@@ -365,35 +365,37 @@ Set-AzRoleDefinition -InputFile "C:\CustomRoles\customrole1.json"
 
 ## Delete a custom role
 
-To delete a custom role, use the [Remove-AzRoleDefinition](/powershell/module/az.resources/remove-azroledefinition) command.
-
-The following example removes the *Virtual Machine Operator* custom role.
-
-```azurepowershell
-Get-AzRoleDefinition "Virtual Machine Operator"
-Get-AzRoleDefinition "Virtual Machine Operator" | Remove-AzRoleDefinition
-```
-
-```Example
-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
-```
-
+1. Remove any role assignments that use the custom role. For more information, see [Find role assignments to delete a custom role](custom-roles.md#find-role-assignments-to-delete-a-custom-role).
+
+1. Use the [Remove-AzRoleDefinition](/powershell/module/az.resources/remove-azroledefinition) command to delete the custom role.
+
+    The following example removes the *Virtual Machine Operator* custom role.
+    
+    ```azurepowershell
+    Get-AzRoleDefinition "Virtual Machine Operator"
+    Get-AzRoleDefinition "Virtual Machine Operator" | Remove-AzRoleDefinition
+    ```
+    
+    ```Example
+    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
 
 - [Tutorial: Create an Azure custom role using Azure PowerShell](tutorial-custom-role-powershell.md)

articles/role-based-access-control/custom-roles-rest.md

@@ -12,7 +12,7 @@ ms.service: role-based-access-control
 ms.workload: multiple
 ms.tgt_pltfrm: rest-api
 ms.topic: how-to
-ms.date: 03/19/2020
+ms.date: 07/28/2022
 ms.author: rolyon
 ms.reviewer: bagovind
 
@@ -314,6 +314,8 @@ To update a custom role, use the [Role Definitions - Create Or Update](/rest/api
 
 To delete a custom role, use the [Role Definitions - Delete](/rest/api/authorization/roledefinitions/delete) REST API. To call this API, you must be signed in with a user that is assigned a role that has the `Microsoft.Authorization/roleDefinitions/delete` permission on all the `assignableScopes`. Of the built-in roles, only [Owner](built-in-roles.md#owner) and [User Access Administrator](built-in-roles.md#user-access-administrator) include this permission.
 
+1. Remove any role assignments that use the custom role. For more information, see [Find role assignments to delete a custom role](custom-roles.md#find-role-assignments-to-delete-a-custom-role).
+
 1. Use the [Role Definitions - List](/rest/api/authorization/roledefinitions/list) or [Role Definitions - Get](/rest/api/authorization/roledefinitions/get) REST API to get the GUID identifier of the custom role. For more information, see the earlier [List custom roles](#list-custom-roles) section.
 
 1. Start with the following request:

articles/role-based-access-control/custom-roles.md

@@ -7,7 +7,7 @@ manager: karenhoran
 ms.service: role-based-access-control
 ms.topic: conceptual
 ms.workload: identity
-ms.date: 06/28/2022
+ms.date: 07/28/2022
 ms.author: rolyon
 ---
 
@@ -190,6 +190,18 @@ Just like built-in roles, the `AssignableScopes` property specifies the scopes t
 | Update a custom role | `Microsoft.Authorization/ roleDefinitions/write` | Users that are granted this action on all the `AssignableScopes` of the custom role can update custom roles in those scopes. For example, [Owners](built-in-roles.md#owner) and [User Access Administrators](built-in-roles.md#user-access-administrator) of management groups, subscriptions, and resource groups. |
 | View a custom role | `Microsoft.Authorization/ roleDefinitions/read` | Users that are granted this action at a scope can view the custom roles that are available for assignment at that scope. All built-in roles allow custom roles to be available for assignment. |
 
+## Find role assignments to delete a custom role
+
+Before you can delete a custom role, you must remove any role assignments that use the custom role. If you try to delete a custom role with role assignments, you get the message: `There are existing role assignments referencing role (code: RoleDefinitionHasAssignments)`.
+
+Here are steps to help find the role assignments before deleting a custom role:
+
+- List the [custom role definition](role-definitions-list.md).
+- In the [assignable scopes](role-definitions.md#assignablescopes) section, get the management groups, subscriptions, and resource groups.
+- Iterate over the assignable scopes and [list the role assignments](role-assignments-list-portal.md).
+- [Remove the role assignments](role-assignments-remove.md) that use the custom role.
+- [Delete the custom role](custom-roles-portal.md#delete-a-custom-role).
+
 ## Custom role limits
 
 The following list describes the limits for custom roles.

articles/role-based-access-control/troubleshooting.md

@@ -9,7 +9,7 @@ ms.service: role-based-access-control
 ms.workload: identity
 ms.tgt_pltfrm: na
 ms.topic: troubleshooting
-ms.date: 07/27/2022
+ms.date: 07/28/2022
 ms.author: rolyon
 ms.custom: seohack1, devx-track-azurecli, devx-track-azurepowershell
 ---
@@ -277,7 +277,7 @@ There are role assignments still using the custom role.
 
 **Solution**
 
-Remove those role assignments and try to delete the custom role again.
+Remove the role assignments that use the custom role and try to delete the custom role again. For more information, see [Find role assignments to delete a custom role](custom-roles.md#find-role-assignments-to-delete-a-custom-role).
 
 ### Symptom - Unable to add more than one management group as assignable scope