How to Search the Microsoft 365 Audit Log for Events

Rich Source of Information About Microsoft 365 Workloads

The Microsoft 365 audit log (aka the unified audit log) is a rich source of information about what happens inside a tenant. Audit events generated by workloads go through an ingestion process to be added to the log to ensure that every event has a common set of fields like the date when the event occurred, the account responsible for the event, and the name of the event. In addition, a workload-specific payload of audit data is inserted into the AuditData property of events. This data varies from workload to workload. Interpreting the workload data is one of the challenges of dealing with the audit log that quickly becomes second nature (when you’ve done it often enough).

You can search the Microsoft 365 audit log using the Audit facility in the Microsoft Purview Compliance portal (Figure 1). This is acceptable when you’re looking for a specific event, but if you need to cast a wider net to look for events that might lead you to an answer, it’s easier and faster to do the job with PowerShell.

Who Did What or What Happened?

Most auditing queries are run to answer “who did what” questions. In other words, you want to know who performed a specific action. For instance, who deleted a document, created a group, recorded a Teams meeting, or sent a message from a shared mailbox. Chapter 21 of the Office 365 for IT Pros eBook contains many practical examples of parsing audit data from multiple workloads to answer who did what questions.

Sometimes you need to know what happened to a particular object, like a document or a user. Finding audit events for one or more documents is easy – all you need to do is pass the document names in the ObjectIds parameter. In this example, we create an array of document names to search for and then pass the array as the ObjectIds parameter for the call to Search-UnifiedAuditLog:

array]$docs = "New Signature API for Email Signatures.docx", "Controlling default creation of online meetings with OWA.docx", "Anticipating Microsoft Ignite 2020.docx"
$Records = Search-UnifiedAuditLog -ObjectIds $docs -StartDate 1-Sep-2020 -EndDate 1-Oct-2020 -ResultSize 500

The events found are for all actions performed against the documents, such as being modified or downloaded. The same technique works for users:

[array]$Users = "Oisin.Johnston@office365itpros.com", "Kim.Akers@office365itpros.com"
$Records = Search-UnifiedAuditLog -ObjectIds $Users -StartDate 1-Sep-2020 -EndDate 1-Oct-2020

This search returns events for actions performed for these users (like being added to a group membership) rather than events performed by the users.

Actions Performed Against a Microsoft 365 Group

Microsoft 365 Groups are not users, so if we want to find the actions performed against a group, we must use the FreeText parameter to search audit records for instances of unique values that identify the group we’re interested in. Fortunately, the object identifier for a group is a good search term. In this example, we extract the object identifier for a Microsoft 365 group and use it to search for audit events. We then group the audit events to get an overview of the kind of activity performed against our target:

$ObjectId = Get-UnifiedGroup -Identity "Office 365 for IT Pros" | Select -ExpandProperty ExternalDirectoryObjectId
$Records = Search-UnifiedAuditLog -FreeText $ObjectId -StartDate (Get-Date).AddDays(-90) -EndDate (Get-Date).AddDays(+1) -ResultSize 1000 
$Records | Group Operations | Sort Count -Descending | Format-Table Name, Count

Name                      Count
----                      -----
RecipientChange              17
TabUpdated                   10
TabAdded                      4
Remove member from group.     3
MemberRemoved                 3
Add member to group.          3
Update group.                 2
MemberAdded                   2
TabRemoved                    1
Set-UnifiedGroup              1
PutPermissions                1
Assign label to group.        1
StreamInvokeVideoSetLink      1

The technique also works for finding audit records for security groups (but not for distribution lists). It also works for Azure AD accounts, including guest users, but it’s much slower than using the ObjectIds parameter. As the name implies, FreeText means that a free text search is used to find matching audit events. In a large tenant, a free text search across potentially millions of records won’t be fast.

Remember that a single action can result in multiple events. For instance, if you add someone to a group, the MemberAdded and Add member to group events are captured by different workloads and ingested into the audit log. The duplication is easily detected by comparing the creation date for the events.

Mine the Audit Log

Every Office 365 administrator should know how to mine the Microsoft 365 audit log to answer questions about their tenant. It’s not hard and you’ll understand a lot more about how Office 365 works once you spend time deep in audit data. That doesn’t sound fun, but it’s better than it seems.