Include eligible assignments when retiring an Azure custom role

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.

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. Source retrieved September 9, 2026.