An Admin's Guide to Navigating Audit Logs in Office 365 (2024)

Office 365 Audit logs are your go-to resource if you’re interested in what’s going on in your environment, be that managing Office 365 Groups, or what’s going on with your various resources on Azure, or even who is accessing and moving files around.

In some cases, because of regulations, you might need to keepa record of the various actions that are performed on the environment. Since Office 365 has a rigid data retention period for Office 365 audit logs, you might even need to handle and store them using a custom solution.

We’ve already talked about audit logs on SharePoint On-premises in theSharePoint Audit Logs: A Key to Better SharePoint Managementblog.The reasonswhy you might want to keep the Office 365 audit logs at hand hasn’t changed that much in the move from SharePoint On-premises to Office 365.

If we call SharePoint On-premises a complex platform, Office 365 is a huge ecosystem containing multiple interconnected services (Exchange, Teams, Azure, and OneDrive, just to name themore popularones). Any solution that tracks Office 365 activity for the purposes of auditing must include activity made on the services that make up the platform.

Now, what options do we have when we need to do Office 365 auditing? A few, and I’ll give an overview of SharePoint’s audit log reports and Office 365 audit logs for admins.

SharePointOnline audit log reports

If you’ve worked with SharePoint On-premises and have seen its audit logs, you’ll notice a lot has stayed the samein its move to the cloud. These logs can answer most of the questions you might have regarding your SharePoint sites. The SharePoint Online audit log reports will give you information about:

• Edited items
• Checked-out and checked-in items
• Items that have been moved and copied to other locations in the site collection
• Deleted and restored items
• Changestocontent typesand columns
• Search queries
• Changestouser accounts and permissions
• Changed audit settings and deleted audit log events
• Workflow events
• Custom events

There is no longer an option to record opened, downloaded, and viewed items in the cloud version. I would guess that was changed in order to reduce the resource cost on Microsoft’s side since those events are the most frequently occurring and usually the least critical. But I can’t find any official article on this omission.

How to turn on Office 365 audit logs

To enable Office 365 auditing, SharePoint audit logging needs to be set up for each site collection separately, but you can automate it with a simple PowerShell script and a list of your site collections.

SharePointOnline’saudit logs have a few constraints.The minor one is that youcannot access the raw audit log dataprogrammatically.Unlike on-premises, there is no endpoint you can connect to if you want to access the collected records to create custom reports.

You can however choose from a selection of Excel reports that should satisfy most of your needs, but you’ll have to generate reports for each site collection separately. This also means that if you want to process the data further, you’re stuck with downloading and parsing Excel documents.

The bigger constraint relates to what is not collected: everything outside of SharePoint isignored. In an environment such as Office 365, this means many actions, such as any performed in Azure Active Directory or Exchange for instance,will not be visible here.

Note that these logs have a maximum data retention period of 90 days, which is something Syskit Point can help you with as it can store Office 365 audit logs for longer periods.

Office 365 audit logs

Office 365 audit logs capture details about system configuration changes and access events, with details to identify who was responsible for the activity, when and where the activity took place, and what the outcome of the activity was.

Where are Office 365 audit logs stored?

You can find Office 365 audit logs in the Microsoft Purview Compliance Center. While other logs are limited in scope to aparticular service, these are collected from multiple Office 365 services and consolidated into a single, searchable log(and they catch page and file views).

How do I know if Office 365 audit logs are enabled?

Audit logs are enabled by default, but Microsoft still recommends checking the auditing status when setting up a new Microsoft 365 tenant.

To check if it’s turned on, navigate to the Audit log search and clicktheStart recording user and admin activitybutton if it is displayed.You will have to wait a few hours for the service to prepare itself for use, but you won’t need to do this more than once per tenant.

Once the preparation on the Office side is complete, audited events will start appearing in the log. Depending on theparticular service, it can take up to 30 minutes or even up to 24 hours for an event to be shown in the audit log. Here’s thefull list of audited services and actions.

How long are Office 365 audit logs kept?

As of October 17, 2023, logs are kept for 180 or 365 days, depending on the license. They can be retained for longer than the default 180 days if the user who generates the audit log (that is, the user who performs the audited activity) is assigned an Office 365 E5 of Microsoft 365 E5 license or has a Microsoft 365 E5 Compliance or E5 eDiscovery and Audit add-on license. It is possible to retain audit logs for up to 10 years, but the user must also be assigned a 10-year audit log retention add-on license in addition to an E5 license. You can find more information on audit log retention policies here.

You canexport the results of a search into aCSV fileto store and analyze further. The format is not made to be read by humans at a glance; it is a CSV file containing JSON objects, but that also makes it easy for processing by an application. The main issue you’ll come across is that most of the properties are lumped into an AuditDataJSON, whichcontains very different properties depending on the audit event.

There’s alsotheoption ofprogrammatically downloadingthe audit logsfor use in your solutions.This way, you can regularly download the newly available events using the available API’s, usingeitherPowerShell or REST.

Accessing audit logsthroughExchange management tools

This method is easier to use since you’ll only need to have PowerShell installed and haveeither theAudit LogsorView-Only Audit Logsroleassigned in Exchange (global admins should have this by default).

To connect to an Exchange Online with PowerShell,this is the script you’ll want to run:

Connect-ExchangeOnline -UserPrincipalName [email protected] -SkipLoadingFormatData

This willestablish a connection to Exchange Onlineand allow you to run cmdlets associated with Exchange. After you’re done with the session, it’s recommended to close it using the following:

Disconnect-ExchangeOnline -Confirm:$false

If you’re having trouble with the execution policy on your machine, you will need to firstrun:

Set-ExecutionPolicy RemoteSigned

The only Exchange cmdlet we’re interested in right now isSearch-UnifiedAuditLog. It has a simple basic signature but allows for a lot of customization (find out morehere).

Search-UnifiedAuditLog -StartDate 04/24/2019 -EndDate 04/25/2019

This command will returnaudit recordsforthe specified date, up to a maximum of 100. You can specify a larger number of recordstoreturn, or you can use paging by specifying aSessionIdand using theReturnNextPreviewPageSessionCommand.

The returned data contains the general data about the event (RecordType, CreationData, UserIds, and Operations) and the AuditData JSON, which contains the event description and whose properties depend on the specific event type.

All the data contained in the Security & Compliance Search can be queried fromhere, which effectivelymeansthey share the same data retention period.This is important to note because the other method differs in this regard.

You can find more info about connecting to Exchange Online by remote PowerShellhere.

Office 365 management API

This API provides access to events from Office 365 audit logs. The data available hereisthe same as shown in the search log, with very few differences.The major one beingyou can only get data for the last 7 days, while others make the data available for up to 90 days.

The audit data is made available using blobs – the service periodically collects events and organizes them into these collections (or blobs), which can then be downloaded. The events contained in the blobs are not in any particularorderbutarebundled up according to the time when the service collected them.

This means that an older event might appear in a very recent blob (according to Microsoft, in case of a service outage, this might mean a delay of 5 days or more). What this means is thatyou cannot use this service for alertssince there is no guarantee an event will be made available in a timely manner.

Ofthe two possible APIsto use to collect Office 365 audit logs,this one isthe recommendedone.

How to start collecting data?

To start collecting this data, you will need to create a new application on your Azure first. Then,using that application,we’llstart subscriptions for the various event content types available. The application requires theActivityFeed.ReadandServiceHealth.Readapplication and delegated permissions, andyou’ll need to generate a client secretto authenticate your application.

We’ll use the client secretinthe next steps, so make sure to store it somewhere.

The following examples will be written in PowerShell, buttheycan be easily rewritten in almost any other programming language.

Using the following script and the values of your clientId, clientSecret and tenantDomain,we’ll get an access tokenthat we can use in subsequent calls to the API.

$clientID = "00000000-0000-0000-0000-000000000000" $clientSecret = "]t;{K!.;andsomemoregibberish" $tenant = "contoso" $tenantdomain = "$tenant.onmicrosoft.com" $loginURL = "https://login.microsoftonline.com/" $resource = "https://manage.office.com" $body = @{grant_type="client_credentials";resource=$resource;client_id=$clientID;client_secret=$clientSecret} $oauth = Invoke-RestMethod -Method Post -Uri $loginURL/$tenantdomain/oauth2/token?api-version=1.0 -Body $body $headerParams = @{'Authorization'="$($oauth.token_type) $($oauth.access_token)"}

TheheaderParamsattribute now contains the access token. Using this token, we’ll be able to start the subscriptions to each of the audit types (Audit.AzureActiveDirectory,Audit.Exchange,Audit.SharePoint,Audit.General, andDLP.All). To start asubscription,run this command:

Invoke-WebRequest -Method Post -Headers $headerParams -Uri "https://manage.office.com/api/v1.0/$tenant/activity/feed/subscriptions/start?contentType=Audit.AzureActiveDirectory" 

To start a subscriptionforthe otheraudittypes, simply replacethecontentTypeparameter value with the names of the other audit types.

You can check the activated subscriptions with the following:

Invoke-WebRequest -Headers $headerParams -Uri "https://manage.office.com/api/v1.0/$tenant/activity/feed/subscriptions/list"

Assuming the scripts ran successfully, you should now be able to queryforaudit blobs and download their contents like so:

Invoke-WebRequest -Method GET -Headers $headerParams -Uri "https://manage.office.com/api/v1.0/$tenant/activity/feed/subscriptions/content?contentType=Audit.AzureActiveDirectory"

This request will return a JSON object containing contenturisfor events that have been made available today. You can choose a different time period byspecifying astartTimeandendTimeparameter(both need to be specified and must not span more than 24 hours).

Invoke-WebRequest -Method GET -Headers $headerParams -Uri "https://manage.office.com/api/v1.0/$tenant/activity/feed/subscriptions/content?contentType=Audit.AzureActiveDirectory&startTime=2019-04-25T00:00&endTime=2019-04-25T11:59"

In any case, the returned JSON object should containuriswe can use to collect events collected in the time period (remember, we don’t have a guarantee the eventactually occurredin that time period, only that it was collected then).An example of such a request anduriwould look like this:

Invoke-WebRequest -Method GET -Headers $headerParams -Uri 'https://manage.office.com/api/v1.0/00000000-0000-0000-0000-000000000000/activity/feed/audit/20190425071547312049798$20190425071747444061084$audit_azureactivedirectory$Audit_AzureActiveDirectory$emea0035'

This will return a collection of events in a JSON format. The eventshave schemas depending on the audit event type they’re describing.Microsoft has defined about two dozen different schemas (a couple more or less, depending on how you count them since a few are considered base and aren’t used independently of others). Each event will have CreationTime, RecordType, Operation, and ResultStatus properties.

According to its type, it will also have several other properties used to describe thedetails of the action that created the record (these extra details can be found by examining a single row in the Audit log search and expanding theMore informationtab). This can be anything from the user that initiated the action, where the action was made, or what the target was.

How to understand these properties?

Some of these properties are easier to make sense of than others since connecting an email to a particular user is straightforward. But it’s much less so to connect a group id to a group name or a team site id to an Office 365 Group.Microsoft hasdocumented the schemas and their properties,but note that some record types are not officially documented.

You can find out more about the Office 365 Management API by checking outthe official resources.

If we compare the PowerShell API to the REST one, we can see that the Search-UnifiedAuditLogcmdlet, with its numerous optional parametersis more suited for searching and filtering logsin search of a specific record, but not so much for collecting new records as they’re coming in since a record’s creation time is not the same time the record was made available. The REST API is much more appropriate for collecting and storing audit records. Since the collection of events in the blobs does not change, you only need to collect new blobs as they become available.

Where Syskit Point comes in

We’ve seen that finding what you’re looking for is rarely easy. Especially if you just want an overview of what’s happening with a given user or site. The default logs are verbose,and because they are generic,they tend not to focus on what is important in a given context.The filters are nice, but you need to know the exactURLof an object beforehand to view the actions associated with it.

The data retention is stingy, although understandably so since Microsoft needs to store a lot of data. And every extra day of data retention they allow means an enormous amount of extra storage space required on their end.For this and other reasons,we’ve made our own custom solution for storing, searching, and exportingOffice 365 audit logs. It stores data locally, meaning you can decide how much of it you want to store and for how long.

It’s easily accessible from most reports,allowing you toeasily check the audit logsrelated to a certainSharePointsiteand theitems in its document libraries, or you caneasily check the list of actions made by or on a certain user. We’ve tried to make it aseasy as possibleto read so you can see what’s importantat a glance.