Administrative units in Azure AD are the rough equivalent of an OU, and have been around for years. They are a cornerstone of Azure AD’s RBAC model, and as such we’ve covered them extensively over the years. As Microsoft is slowly ramping up support for AUs across various workloads and endpoints, their role continues to grow in importance. In this article, we will examine how Exchange Online supports Administrative units and highlight some scenarios they can be useful for.
As Administrative units are an Azure AD concept, their creation and management remains an Azure AD operation (nowadays you can use either the Azure AD blade, PowerShell or the Graph API). In order to facilitate their usage within Exchange however, Microsoft has introduced the Get-AdministrativeUnit cmdlet, which you can use to list all available AUs within the tenant. Here’s an example:
Get-AdministrativeUnit Name DisplayName ---- ----------- 18560689-d221-4f88-a713-17e973cf6498 New AU 3cc9eefb-c0ab-4eb3-aeee-95f7da2ba493 Domain 4702b0dc-3ca5-4046-bf46-363a50ecb743 Domain-based 6ee4baa4-f864-4467-9cd2-f0832a323546 Shared mailboxes only b42de8c9-7062-4cc0-8c85-f6ae79bdb839 Bulgaria users
As evident from the output above, the Name (as well as Identity/Id) value for the corresponding object, which is of the Deserialized.Microsoft.Exchange.Data.Directory.SystemConfiguration.ADAdministrativeUnit type, matches its ExternalDirectoryObjectId value. Not much else is revealed even after examining the full set of properties for the object. After all, AUs are simply a container for objects, so you will only ever need their identifier and the list of members. Speaking of which, Exchange Online does not expose any direct cmdlet to list members of an AU, however you can use a -RecipientPreviewFilter query to get the list. As usual, you will need to obtain the DistinguishedName value first, and then pair it with the AdministrativeUnits keyword. Here’s an example:
$dn = (Get-AdministrativeUnit -Identity 18560689-d221-4f88-a713-17e973cf6498).DistinguishedName Get-Recipient -RecipientPreviewFilter "AdministrativeUnits -eq '$dn'" Name RecipientType ---- ------------- shared UserMailbox
If we check the AU membership on Azure AD side, we will see the exact same list of members returned. Technically, you can also use the same method to report on membership of AUs with dynamic membership rules. Things of course get more interesting when we have other object types added as members of the AU, as Exchange Online cannot recognize devices and such. And as we’ve discussed in several articles already, even regular “user” objects are not returned by default. Overall, if you want a proper list, it’s best to check on Azure AD side, as the Exchange methods will only return a list of objects supported by Exchange. Then again, those are the objects you will be configuring permissions for, so that’s still a valuable information.
Now that we know how to list AUs in Exchange, as well as their members, how do we go about leveraging them for the purposes of RBAC? Basically, we have two options. The first, and least recommended one, is to create a management scope based on an AdministrativeUnits query, much like in the examples we used above. Here’s an example of how to do that:
$dn = (Get-AdministrativeUnit -Identity 18560689-d221-4f88-a713-17e973cf6498).DistinguishedName New-ManagementScope -Name AUbased -RecipientRestrictionFilter "AdministrativeUnits -eq '$dn'"
The second method, and the one actually recommended by Microsoft, is to leverage the newly introduced -RecipientAdministrativeUnitScope parameter for the New-ManagementRoleAssignment cmdlet. As the name suggests, you can use said parameter to directly scope the newly created management role assignment to just recipients that are members of a given AU, where you can reference the AU in question by its name or objectID (as in, no need to use the DistinguishedName value). At least in theory, as in my tests, using the AU’s display name as input resulted in errors and I had to use the objectID instead. Still, the objectID is easier to handle than the DistinguishedName 🙂
With this information at hand, here’s how to configure an AU-scoped role assignment. In the examples below, we will grant the “User options” management role to a specific user (“gosho”), and scope the management role assignment to just members of the “Bulgaria users” Administrative unit. The following cmdlets can be used:
#Referencing the AU by display name seems to result in an error New-ManagementRoleAssignment -User gosho -Role "User options" -RecipientAdministrativeUnitScope "Bulgaria users" #You can pass the object however New-ManagementRoleAssignment -User gosho -Role "User options" -RecipientAdministrativeUnitScope (Get-AdministrativeUnit "Bulgaria users") #Or just use the objectID New-ManagementRoleAssignment -User gosho -Role "User options" -RecipientAdministrativeUnitScope "b42de8c9-7062-4cc0-8c85-f6ae79bdb839"
As detailed in our previous article, you can also use Administrative units to create scoped management role assignments for applications. The syntax is the same, though you will have to use the -App parameter instead of -User, and specify one of the supported SP-assignable management roles. Here’s an example:
New-ManagementRoleAssignment -App 2a63aee1-db17-489d-a8ab-d40971066292 -Role "Application Mail.ReadBasic" -RecipientAdministrativeUnitScope (Get-AdministrativeUnit "Bulgaria users")
To list all existing management role assignments scoped to administrative units, use the -RecipientWriteScope parameter of the Get-ManagementRoleAssignment cmdlet:
Get-ManagementRoleAssignment -RecipientWriteScope AdministrativeUnit Name Role RoleAssigneeName RoleAssigneeType AssignmentMethod EffectiveUserName ---- ---- ---------------- ---------------- ---------------- ----------------- User Options-gosho User Options gosho User Direct gosho
The Get-ManagementRoleAssignment cmdlet also supports a -RecipientAdministrativeUnitScope parameter, which in theory should allow us to filter the set of management role assignments by a specific AU. Unfortunately, using the parameter currently seems to always result in an error, regardless of the value provided for the AU identifier. An alternative approach to achieve the same task is to leverage client-side filters, based on the value of the CustomRecipientWriteScope property, which will contain the AU’s identity. Here’s an example:
Get-ManagementRoleAssignment -RecipientWriteScope AdministrativeUnit | ? { $_.CustomRecipientWriteScope -eq "b42de8c9-7062-4cc0-8c85-f6ae79bdb839" }
Name Role RoleAssigneeName RoleAssigneeType AssignmentMethod EffectiveUserName
---- ---- ---------------- ---------------- ---------------- -----------------
User Options-gosho User Options gosho User Direct gosho
Note that even though the Get-ManagementRoleAssignment cmdlet supports direct queries based on the CustomRecipientWriteScope value, they also seem to always throw an error, at least currently.
Lastly, if order to test a given AU-scoped management role assignment, all you need to do is login with the corresponding user and try to run one of the allowed cmdlets against an object within the AU scope. Compare the results with running the cmdlet against an object outside of the AU scope and you will know whether the AU-scoped management role assignment works as expected. And for application-based management role assignments, you can leverage the Test-ServicePrincipalAuthorization cmdlet, as detailed in our previous article.
In summary, the Exchange Online RBAC model now has support for scoping management role assignments based on membership of Azure AD administrative units. This is a welcome addition, which brings the ExO and Azure AD RBAC models closer together, and enables additional scenarios. Going forward, customers can use an unified AU-based scoping approach for restricting both Azure AD and Exchange Online operations. That said, good old management scopes in Exchange Online remain supported and can still help you address some corner scenarios, such as where you want to scope the objects based on the value of some Exchange-specific attribute (which is not exposed in Azure AD).
Going forward, we’re likely see administrative units incorporated in the Exchange Admin Center, and hopefully, an UI-based approach for managing (or at the very least viewing) management role assignments. Stay tuned!
1 thought on “ExO RBAC improvements #2: Support for administrative units”