Table of Contents
Distribution Lists are Entra ID Groups – Kind Of
A recent discussion about how to track changes in Microsoft 365 groups prompted the question about how to generate the same information about distribution list changes? The issue here is that distribution lists are not fully-fledged Entra ID objects. Instead, they are Exchange Online objects hosted in the Exchange Online Directory Store (EXODS) and synchronized to Entra ID. In fact, Exchange Online and Entra ID use a dual-write mechanism to make sure that changes made to distribution lists happen in both directories simultaneously. If the dual write fails for any reason, the update is not applied to either directory.
Although Entra ID knows about distribution lists, you cannot use the Entra ID Graph APIs to update distribution list properties or add or remove group members. Everything is done through Exchange Online.
Finding Audit Records for Distribution List Changes
All of which is a complicated way of saying that the technique used to report changes made to Microsoft 365 groups won’t work. Although the updates for distribution lists make their way into Entra ID and subsequently generate audit events for those changes, the “actor” (the process that updates Entra ID) is a system background job called Microsoft Substrate Management. To discover the human who update distribution lists, we must consult the audit events logged by Exchange Online rather than Entra ID.
Creating the Script to Report Distribution List Changes
In any case, I started by copying the script to report changes to Microsoft 365 groups so as to have the structure. I then made the following changes:
- Connect to Exchange Online: Apart from the Search-UnifiedAuditLog cmdlet, the cmdlets to fetch distribution list membership and properties are in the Exchange Online module.
- Run the Get-DistributionGroup cmdlet to fetch details of the destruction lists in the tenant. Room lists, which are a special form of distribution list, are excluded.
- Run the Search-UnifiedAuditLog cmdlet to fetch audit records for the last 30 days for actions like adding, removing, and updating distribution lists and distribution list memberships.
- Analyze the audit records to extract details about the different actions. I want to know who performed an action and the distribution list that is involved. In the case of membership additions and removals, I want to know the member added to or removed from the distribution list. Hash tables hold details of distribution lists and user accounts to avoid the need to use the Get-Recipient cmdlet to resolve identifiers multiple times.
- Read the set of distribution lists to generate some information about each list such as the owners, list of members, and counts for the different forms of members (like public folders!).
- Generate a HTML report to capture all the generated information.
- Generate a CSV or XLSX file containing the details of distribution lists. The script creates an Excel worksheet if the ImportExcel module is available.
- Connect to the Microsoft Graph PowerShell SDK to create and send email with details of what’s been found (Figure 1). Remember, Microsoft will remove basic authentication for the SMTP AUTH client submission protocol from Exchange Online sometime in late 2027, so there’s no point in using the Send-MailMessage cmdlet to send email.
Download the Script to Report Distribution List CHanges
You can download the script from the Office 365 for IT Pros GitHub repository. The nice thing about PowerShell is that if you don’t like the code, feel free to change it to meet your requirements. Be nice to the community and publish your updates through GitHub. You know that it makes sense!
Need help to write and manage PowerShell scripts for Microsoft 365, including Azure Automation runbooks? Get a copy of the Automating Microsoft 365 with PowerShell eBook, available standalone or as part of the Office 365 for IT Pros eBook bundle.