Table of Contents
Entra ID Administrative Units and Compliance Roles Limit User Access to Microsoft 365 Audit Log Data
Entra ID administrative units are a premium feature that allows organizations to create partitions within the directory (analogous to organizational units in Active Directory). Microsoft Purview compliance solutions have recently added support for administrative units to restrict access of administrators to compliance activities for certain accounts based on membership of selected administrative units.
Although administrative units can include user accounts, groups, and devices, from a compliance perspective, Exchange Online is only interested in user accounts with mailboxes. Many compliance activities such as data lifecycle management (retention processing) target mailboxes, so it makes sense that Exchange Online should respect the boundaries imposed by sets of accounts listed in administrative units when it’s asked to provide information.
To retrieve details of the user and group objects that are members of administrative units, run the script described in this article.
Exchange Online Cmdlet to Work with Administrative Units
The Exchange Online management module contains the Get-AdministrativeUnit cmdlet. The cmdlets retrieves information about Entra ID administrative units stored in the Exchange Online directory. Exchange Online doesn’t synchronize updates about administrative units and membership immediately and it can take up to ten minutes for synchronization (new administrative units, changes to membership, etc.) to happen. After synchronization, run Get-AdministrativeUnit to view the details of administrative units as known to Exchange Online:
Get-AdministrativeUnit Name DisplayName ---- ----------- 0555a6cd-f1eb-4843-ba62-a362db719704 Project Management (Sales) dynamic administrative unit 0ee53a45-bbee-4571-a407-56acc0b944a1 Ireland 112f5e71-b430-4c83-945b-8b665c14ff25 Global HQ dynamic administrative unit 150dccad-f8b8-4e54-9246-89834b8b5a25 Group HQ Users
This output is similar to that of the Get-MgDirectoryAdministrativeUnit from the Microsoft Graph PowerShell SDK:
Get-MgDirectoryAdministrativeUnit | Format-Table Id, DisplayName
There’s no equivalent of the Get-MgBetaAdministrativeUnitMember cmdlet to return a set of members for an administrative unit, but this can be done by running the Get-Recipient cmdlet to resolve a recipient filter based on the distinguished name of the administrative unit object (the copy in the Exchange Online directory rather than Entra ID). For example:
$AUName = (Get-AdministrativeUnit -Identity 'Information Technology dynamic administrative unit').distinguishedName [array]$AUMembers = Get-Recipient -RecipientPreviewFilter "AdministrativeUnits -eq '$AUName'" $AUMembers | Format-Table DisplayName, PrimarySmtpAddress, ExternalDirectoryObjectId DisplayName PrimarySmtpAddress ExternalDirectoryObjectId ----------- ------------------ ------------------------- Ben Owens (DCPG) Ben.Owens@office365itpros.com a3eeaea5-409f-4b89-b039-1bb68276e97d Andy Ruth (Project Director) Andy.Ruth@office365itpros.com fdc6b121-44b8-4262-9ca7-3603a16caa3e
Using a recipient filter might seem convoluted, but it’s no more complicated than the steps required to retrieve membership information for an administrative unit with the Graph SDK:
$AUMembers = Get-MgBetaAdministrativeUnitMember -AdministrativeUnitId (Get-MgDirectoryAdministrativeUnit -Filter "displayName eq 'Information Technology dynamic administrative unit'" ).Id -All
[array]$MemberUsers = $AuMembers.additionalProperties | Where-Object {$_.'@odata.type' -eq "#microsoft.graph.user"}
$Memberusers | ForEach-Object { Write-Host $_.displayName “ “ $_.mail}
Some of this is due to the way that Graph requests return information, and part is due to some SDK foibles. It’s especially annoying in this case that the property names are case sensitive. “displayName” works but “DisplayName” does not.
Connecting Exchange Online and Purview Audit
The Audit Log search feature in the Microsoft Purview compliance portal supports administrative units. In other words, you can assign the Audit Reader compliance role to users to allow them to manage one or more administrative units. Purview Audit searches will limit the records retrieved from the Microsoft 365 audit log to those generated by members of the selected administrative units.
Figure 1 shows the parameters for a new search, which is limited to the United States administrative unit. Administrators can only choose administrative units that they have access to or search for audit events across the entire organization (the previous default).
When the search completes, the audit events are for actions performed by members of the selected administrative unit. The search works by looking at the AssociatedAdminUnits property in audit events. The property stores the identifier of the administrative units a user account is a member of (accounts can belong to multiple administrative units) and is updated for events when the Microsoft 365 audit log ingests data from workloads. You can see the administrative unit information in the details of audit events found by Audit search (Figure 2).
Very importantly, changes made to administrative unit membership do not replicate to previous audit events. For instance, if a user joins the United States administrative unit, none of the audit events captured for previous actions are available to administrators limited to searching for audit events associated with the United States administrative unit.
Limiting Access for the Search-UnifiedAuditLog Cmdlet to the Microsoft 365 Audit Log
The Search-UnifiedAuditLog cmdlet is part of the Exchange Online management PowerShell module. Its purpose is to run audit log searches, but currently the cmdlet does not respect administrative unit restrictions imposed by compliance center roles. This might change in the future.
The workaround is to use Role-Based Access Control (RBAC) to limit the data the cmdlet can process, specifically by creating management role assignments. For instance, to assign the Audit Logs management role to a user, run the New-ManagementRoleAssignment cmdlet and specify the user (alias, display name, external directory object id, or primary SMTP address) and the identifier for the target administrative unit.
New-ManagementRoleAssignment -User Ken.Bowers@office365itpros.com -Role "Audit Logs" -RecipientAdministrativeUnitScope "4d3ae8ee-212b-4be4-965c-8b5111d4488e"
Searches run with the Search-UnifiedAuditLog cmdlet by the user holding the role will now respect the administrative unit limit based on the AssociatedAdminUnits property in audit events. For instance, here’s an extract of an audit record generated for an account that belongs to three administrative units.
],
"AssociatedAdminUnits": [
"8a703400-7086-4e13-943a-7ed8df9ecd41",
"4d3ae8ee-212b-4be4-965c-8b5111d4488e",
"150dccad-f8b8-4e54-9246-89834b8b5a25"
]
To resolve the identifiers and check that the correct administrative units are used, extract the data to an array and run the Get-AdministrativeUnit cmdlet against each identifier:
$AdminUnits = ($Records[0].AuditData | Convertfrom-Json).AssociatedAdminUnits
ForEach ($AU in $AdminUnits) { (Get-AdministrativeUnit -Identity $AU).DisplayName }
Group HQ dynamic administrative unit
United States
Group HQ Users
Summarizing Support for Administrative Units in Purview Audit
To summarize, organizations can use administrative units to limit user access to Microsoft 365 audit log data. The limitation depends on the compliance role assigned to the account and the data stamped into audit log records. An Exchange management role assignment is required to apply the same limitation to searches run using the Search-UnifiedAuditLog cmdlet.