Administrative units (AUs) are a cornerstone of Microsoft’s Unified Role-based access control (RBAC) model in Azure AD/Microsoft 365. First introduced back in the end of 2014, they’ve enjoyed a renaissance in recent years, with a horde of much-anticipated features being released. One such feature is the soft-delete functionality, or in other words the ability to recover a deleted Administrative unit, which we will dive into in this article.
To start with, we need just a short refresher. Administrative units are basically a “container” for Azure AD objects, and most of the time they are compared with the Organizational units concept within on-premises AD. Unlike OUs however, deleting an Administrative unit does not impact any of its member objects. One might ask then, why is soft-deleting and recovering AUs so important then? Well, as they are used to delegate permissions and scope access, and can sometimes contain thousands of member objects, it’s all about saving you the additional overhead of recreating a deleted AU.
And with that, we can finally talk about the topic at hand, namely soft-deleting and recovering administrative units. A warning is due here – for the time being at least, this functionality is only supported via the Graph API, and not exposed in either the Azure AD blade of Entra admin center’s UI. And since permissions are the ever-present obstacle before using any Graph API endpoint, let’s answer this question as well – you will need the AdministrativeUnit.ReadWrite.All to delete/recover an AU, and the AdministrativeUnit.Read.All to list all soft-deleted ones. Both delegate and application permissions are supported.
The soft-delete and recover functionality works the same way as for any other supported directory object. In other words, you issue a query against the /directory/deletedItems/ Graph API endpoint. For example, to list all soft-deleted AUs within the tenant, you can use the following query:
GET https://graph.microsoft.com/v1.0/directory/deletedItems/microsoft.graph.administrativeUnit
Note that we have OData cast to specifically request the set of Administrative unit objects to be returned, as the endpoint does not support generic (unscoped) GET queries. In any case, as we currently don’t have any soft-deleted administrative units, the resulting response will be an empty list. In case you prefer to use the Graph API SDK for PowerShell, the equivalent cmdlet for the above request would be:
Get-MgDirectoryDeletedItem -DirectoryObjectId microsoft.graph.administrativeUnit
NOTE: the current version of the Graph SDK for PowerShell cmdlets (1.27.0 at the time of writing this post) does not properly display the output of the above cmdlet. Instead, you need to expand the AdditionalProperties property:
Get-MgDirectoryDeletedItem -DirectoryObjectId microsoft.graph.administrativeUnit | select -ExpandProperty AdditionalProperties | % {$_.value}
To see the new features in action, we need to first delete any of the existing AUs. As this action is supported in the UI, you can perform it via the Azure AD blade, Entra admin center or the Microsfot 365 admin center, too. The corresponding action can also be performed via DELETE request against the /administrativeUnits/{id} endpoint, or by leveraging the Remove-MgDirectoryAdministrativeUnit PowerShell cmdlet. Once the deletion is completed, we can refresh the above operation to list any soft-deleted administrative units:
Again, deleting an administrative units object does NOT affect any of the objects that were added as members, but will affect any scoped role assignments that allowed users to manage the set of member objects. So if the deletion was done in error, we can now use the recover functionality to quickly restore the soft-deleted administrative unit to its initial state. This includes not only restoring all its properties, but the full membership list. In scenarios where the administrative unit was configured with dynamic membership rule, it might take a while for the membership to be repopulated.
To recover a soft-deleted administrative unit, we can issue a POST request against the /directory/deleteditems/{id}/restore endpoint, where we need to specify the id of the AU object (as obtained from the previous query). No payload is necessary.
POST https://graph.microsoft.com/v1.0/directory/deletedItems/3cc9eefb-c0ab-4eb3-aeee-95f7da2ba493/restore
If you are planning to perform the same operation via the Graph SDK for PowerShell, use the Restore-MgDirectoryDeletedItem following cmdlet:
Restore-MgDirectoryDeletedItem -DirectoryObjectId 3cc9eefb-c0ab-4eb3-aeee-95f7da2ba493
Few additional remarks. Unlike any other directory object types that currently support the soft-delete/recover functionality, you cannot hard-delete an administrative unit object. In other words, once the AU has been soft-deleted, it will remain in the recycle bin for 30 days, at which point it will be hard-deleted. Unless you have restored it before that, of course. Lastly, in terms of Audit logs, you can expect the corresponding Restore Administrative Unit events to appear shortly after performing the operation above.
And that’s all there is to this nifty new feature. While definitely not anything earth-shattering, it’s a welcome addition, another one in a long string of improvements to AUs we’ve seen over the last few years. Let’s hope this trend will continue until all the missing bits of the RBAC model have been addressed 🙂