Configuring retention for Office 365 audit logs

At the end of January, one of the most anticipated features in the Office 365 compliance arsenal started rolling out, namely the Longer-term retention on audit logs feature, with Roadmap ID #56794. Ever since the Unified audit log was introduced, customers have been asking for longer retention, past the 90 days we get by default, and several long-standing UserVoice requests for the same can be found (exhibits A B C). Clearly, there was a healthy demand for such feature, which become even more apparent past the GDPR enforcement date.

To address this gap, Microsoft started a preview program for a one-year retention period for audit log events. Not much details were released about the program and future plans, and even the current Roadmap item’s description is a bit vague. But, with the rollout of the feature, we finally have the corresponding documentation available, and more importantly the actual code bits we can play with.

So how does one configure longer retention period for audit records? Well, the first question you should ask here is, do I actually need to configure anything? And by that I don’t mean the fact that you might be OK with the 90 day window. Instead, I am referring to the default policy Microsoft has configured for events generated from Azure AD, Exchange Online and SharePoint Online. The list of events covered by this policy can be found here, and all of them will be preserved for a duration of one year. With the caveat that the corresponding user for which the event has been generated must have a qualifying license (O365/M365 E5 or the Microsoft 365 E5 Compliance add-on). And another caveat should be mentioned here – you cannot actually see this policy anywhere in the UI or via the corresponding PowerShell cmdlets. But more on this later.

If you are not satisfied with the list of events covered by the default policy or want to configure a custom retention duration or a policy that applies to events generated by specific set of users, you can create a new policy. To do so from the UI, navigate to the SCC -> Search -> Audit log search, then click the New Retention Policy button on the bottom of the page. In the newly generated pane, enter a Name and Description for the policy, then configure the corresponding Record types and/or Activities. You can find the list of available Record types below, and you can refer to the documentation for the list of individual activities/operations.

ExchangeAdmin, ExchangeItem, ExchangeItemGroup, SharePoint, SyntheticProbe, SharePointFileOperation, OneDrive, AzureActiveDirectory, AzureActiveDirectoryAccountLogon, DataCenterSecurityCmdlet, ComplianceDLPSharePoint, Sway, ComplianceDLPExchange, SharePointSharingOperation, AzureActiveDirectoryStsLogon, SkypeForBusinessPSTNUsage, SkypeForBusinessUsersBlocked, SecurityComplianceCenterEOPCmdlet, ExchangeAggregatedOperation, PowerBIAudit, CRM, Yammer, SkypeForBusinessCmdlets, Discovery, MicrosoftTeams, ThreatIntelligence, MailSubmission, MicrosoftFlow, AeD, MicrosoftStream, ComplianceDLPSharePointClassification, ThreatFinder, Project, SharePointListOperation, SharePointCommentOperation, DataGovernance, Kaizala, SecurityComplianceAlerts, ThreatIntelligenceUrl, SecurityComplianceInsights, MIPLabel, WorkplaceAnalytics, PowerAppsApp, PowerAppsPlan, ThreatIntelligenceAtpContent, LabelExplorer, TeamsHealthcare, ExchangeItemAggregated, HygieneEvent, DataInsightsRestApiAudit, InformationBarrierPolicyApplication, SharePointListItemOperation, SharePointContentTypeOperation, SharePointFieldOperation, MicrosoftTeamsAdmin, HRSignal, MicrosoftTeamsDevice, MicrosoftTeamsAnalytics, InformationWorkerProtection, Campaign, DLPEndpoint, AirInvestigation, Quarantine, MicrosoftForms, ApplicationAudit, ComplianceSupervisionExchange, CustomerKeyServiceEncryption, OfficeNative, MipAutoLabelSharePointItem, MipAutoLabelSharePointPolicyLocation, MicrosoftTeamsShifts, MipAutoLabelExchangeItem

Next, you can also specify the set of Users to which the policy will apply. Leave this blank to have a tenant-wide policy, but don’t forget that only events generated by users that have a matching license will be preserved past 90 days. For the Duration for which to preserve the audit data, you can select between 90 days, 6 months and 1 year. Lastly, you can configure a Priority for the policy, which is an integer between 0 and 10000 (note that the hidden default policy always has the lowest priority). Press the Save button to complete the process.

At this time, the UI does not offer any way to view or change policy settings, so you might as well just manage the entire process via PowerShell. To do so, first connect to the SCC PowerShell endpoint (click here if you need detailed instructions). The cmdlets you will need are as follows:

• Get-UnifiedAuditLogRetentionPolicy – use this cmdlet to retrieve the set of policies currently configured in the tenant. You can use the corresponding parameters to filter the list by -Operation, -RecordType, -RetentionDuration and/or –UserId.
• New-UnifiedAuditLogRetentionPolicy – use this cmdlet to create a new unified audit log retention policy. Apart from the above-mentioned parameters, you will have to specify –Name, –Description, and –Priority. For example, here’s how to create a policy that will retain all audit events generated by a given user for duration of one year:

New-UnifiedAuditLogRetentionPolicy -Name "All activities by XXX" -UserIds user@domain.com -RetentionDuration TwelveMonths -Priority 1

• Remove-UnifiedAuditLogRetentionPolicy – use this cmdlet to remove an existing unified audit log retention policy (sans the default one).
• Set-UnifiedAuditLogRetentionPolicy – use this cmdlet to make changes to existing unified audit log retention policies.

So that’s our short guide on configuring custom retention for unified audit log events in Office 365. Some additional notes, in random order: you can have up to 50 policies; the priority of a policy is evaluated in descending order, that is the higher the value, the higher the priority; you cannot specify custom durations, you can only select a predefined one, in three months increment. It’s also important to mention that the UI currently does NOT support running audit log searches that span more than 90 days in the past. So even though you might have some older events, there is no way to see them.

Using PowerShell and the Search-UnifiedAuditLog cmdlet might help, but in my case mixed results were observed. Even running a “blank” query returned no results for the past year, until the middle of September 2019. Starting from 24 Sep, events start appearing, so in my case the maximum retention window is around 140 days. This will of course improve as time goes on, and after a few months I should expect to have access to the full one year range of events. Whether this will be sufficient for every organization I cannot tell, but luckily there are vendors that offer longer duration, or you can always create your own solution by leveraging the Office 365 Management Activity APIs.