If you manage more than a handful of Azure subscriptions, IAM hygiene quickly becomes one of those tasks everyone knows is important, but few have time to do manually. This script was created to automate one of the most common Azure RBAC cleanup activities: finding and removing Unknown identities from Azure IAM assignments.
Azure role assignments occasionally contain entries where the identity is displayed as Unknown or Identity not found. These typically appear when a user, group, or service principal has been deleted from Microsoft Entra ID while the corresponding RBAC assignment remains in Azure. [learn.microsoft.com]
While these stale assignments may no longer provide access, they clutter documentation, complicate audits, and can create uncertainty during security reviews. As a cloud architect, I prefer keeping IAM environments clean, documented, and easy to understand.
To help automate this process, I created the PowerShell script:
Azure-iam-document_and_remove_unknowns.ps1
The Problem
In large Azure environments, administrators often encounter permissions assigned to identities that no longer exist.
Typical causes include:
Deleted users
Removed security groups
Retired service principals
Guest accounts that were never fully onboarded
Legacy application identities
What the Script Does
The script automates the entire process by:
Enumerating Azure subscriptions
Skipping selected subscriptions (such as Visual Studio or Free subscriptions)
Locating role assignments where the object type is Unknown
Exporting findings to CSV files for documentation
Removing the stale role assignments
Logging removed assignments for audit purposes
This approach provides both cleanup and traceability in a single operation. [github.com], [olavtvedt....ogspot.com]
Why Documentation Matters
One thing I have learned during security reviews is that removing permissions without documenting what was changed creates unnecessary risk.
Before making any modifications, the script exports all findings to CSV files. This gives you:
A record of what was discovered
Evidence during audits
A rollback reference if needed
Historical tracking of IAM cleanup activities
Security Benefits
Cleaning up Unknown IAM assignments offers several advantages:
Improved Visibility
Administrators can focus on valid identities instead of investigating stale objects.
Better Audit Readiness
Security and compliance teams gain cleaner RBAC reports with fewer false positives.
Reduced Operational Noise
Unknown objects often generate questions during reviews and troubleshooting.
Stronger Governance
Regular cleanup demonstrates that access reviews are being actively maintained.
Microsoft confirms that role assignments displayed as Unknown or Identity not found are generally associated with identities that no longer exist and can be safely removed. [learn.microsoft.com]
Example Use Cases
This script is especially useful when:
Preparing for an Azure security audit
Implementing Privileged Identity Management (PIM)
Cleaning up inherited environments
Performing subscription ownership reviews
Supporting ISO 27001 or similar compliance initiatives
Establishing baseline IAM governance
Prerequisites
Before running the script:
Install the Azure PowerShell Az modules
Authenticate using Connect-AzAccount
Ensure you have sufficient RBAC permissions to view and remove role assignments
Review the exclusions and output paths to match your environment
Always test in a non-production environment first and review exported documentation before bulk removal.
Final Thoughts
IAM cleanup is rarely exciting work, but it is one of the simplest ways to improve both security and governance in Azure.
Rather than manually browsing through subscriptions looking for orphaned role assignments, this script provides a repeatable and documented process for identifying and removing stale access entries at scale.
If your Azure environment has been around for a few years, chances are you already have some Unknown assignments waiting to be cleaned up.
Happy scripting! 🚀
Post created with Microsoft Copilot
