# Include eligible assignments when retiring an Azure custom role

> A role definition cannot be deleted while assignments still reference it, including eligible PIM assignments.

- Canonical URL: https://update.dsesecurity.com/updates/dse-20260909-381-include-eligible-assignments-when-retiring-an-azure-custom-role/
- Publisher: Detection Systems & Engineering (DSE Security)
- Author: DSE Security Editorial Team
- Published: 2026-09-10T00:25:35+00:00
- Modified: 2026-09-10T02:01:56+00:00
- Last reviewed by DSE: 2026-09-09
- Resource type: Guide
- DSE priority: Information
- Topics: Cybersecurity, Networks & Infrastructure
- Reading time: 2 minutes

## What you need to know

A role definition cannot be deleted while assignments still reference it, including eligible PIM assignments.

## Potentially affected

Azure custom-role retirement across the role's assignable scopes, including PIM-managed access.

## DSE recommendation

Inventory active and eligible references across every assignable scope before approving role retirement.

## Article

## Source facts

Azure rejects deletion of a custom role that still has referencing assignments with RoleDefinitionHasAssignments. Microsoft’s retirement procedure enumerates the role’s AssignableScopes, removes referencing assignments and explicitly includes eligible custom-role assignments in PIM before deleting the definition.

Renaming a role does not change its role ID. Microsoft recommends using that stable ID in assignment automation instead of relying on the role name. [Microsoft Learn](https://learn.microsoft.com/en-us/azure/role-based-access-control/custom-roles).

## Applicability

Identify the exact role ID, all assignable scopes and the administrators responsible for active and eligible access. This is a retirement review, not authorization to remove every discovered assignment immediately.

## DSE recommendation

DSE recommends preparing a reference inventory and replacement-access decision before deletion. Confirm which users or automation still require the role and obtain approval for their transition. Include eligible PIM entries even when no activation is currently visible. Use the role ID to avoid confusing a renamed definition with another similarly named role.

## Verification

After approved assignment transitions, repeat the reference inventory across the identified scopes. If deletion remains blocked, preserve the error and investigate remaining references instead of broadening the deletion target. Verify that intended replacement access still works and unintended access is absent. Retain the retired role definition and approvals as change evidence without claiming that a successful delete alone proves the access migration was safe.

## Official references

[Microsoft Learn: Azure custom roles – Azure RBAC](https://learn.microsoft.com/en-us/azure/role-based-access-control/custom-roles). Source retrieved September 9, 2026.

## Primary reference

- Name: Azure custom roles - Azure RBAC | Microsoft Learn
- Authority: Microsoft Learn
- URL: https://learn.microsoft.com/en-us/azure/role-based-access-control/custom-roles
- Source publication date: Not stated by the source

## Citation and use

Preferred citation: “Include eligible assignments when retiring an Azure custom role,” DSE Security, https://update.dsesecurity.com/updates/dse-20260909-381-include-eligible-assignments-when-retiring-an-azure-custom-role/
Publishing principles: https://update.dsesecurity.com/updates/dse-updates-editorial-methodology/
Usage and citation policy: https://update.dsesecurity.com/usage/
Copyright © 2026 Detection Systems & Engineering. All rights reserved.