Retrieve granular user actions or usage reports using Search-UnifiedAuditLog cmdlet

This post is a contribution from Manish Joshi, an engineer with the SharePoint Developer Support team

The following blog post demonstrates the steps to retrieve granular user action or usage reports using the Search-UnifiedAuditLog commandlet.

1.       Browse to https://protection.office.com.

           In the left pane, click Search & investigation, and then click Audit log search

Note: You have to first turn on audit logging before you can run an audit log search. If the Start recording user and admin activity link is displayed, click it to turn on auditing. If you don't see this link, auditing has already been turned on for your organization. It will take couple of hours before you are able to see log results in UI or via code.

2.       Browse to https://outlook.office365.com/ecp/

a.       Under permissions – go to admin role

b.       Create a new role, called AuditReportRole

c.       Assign following Roles:

                                 i.            Audit Logs

                               ii.            View-Only Audit Logs

d.       Add Members

Add users (for e.g: garthf@spo.onmicrosoft.com)

e.       Write-Scope --> Default

In the screenshot below. I am creating a new admin role called “AuditReportRole”, assigning minimum required permissions “Audit Logs” and “View-Only Audit Logs” and granting a user “Garth Fort” permission to be able to access the Usage reports.

3.       Use following powershell script, please make changes as per your environment and this will generate .csv file for each user with the actions they have undertaken for last 7 days.

$Username = "garthf@spo.onmicrosoft.com"
$Password = ConvertTo-SecureString 'password' -AsPlainText -Force
$LiveCred = New-Object System.Management.Automation.PSCredential $Username, $Password
 
$session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/ -Credential $LiveCred -Authentication Basic -AllowRedirection

Import-PSSession $session

Connect-MsolService -Credential $LiveCred
 
$Users = Get-MsolUser | Where-Object {$_.UserPrincipalName -notlike "*#EXT#*" }
 
$Users | ForEach {
        
$OutputFile = "C:\SomeFolder\Usage-" + $_.DisplayName + ".csv"

$auditEventsForUser = Search-UnifiedAuditLog -EndDate $((Get-Date)) -StartDate $((Get-Date).AddDays(-7)) -UserIds $_.UserPrincipalName -RecordType SharePoint -Operations FileAccessed,PageViewed,PageViewedExtended


Write-Host "Events for" $_.DisplayName "created at" $_.WhenCreated
 
$ConvertedOutput = $auditEventsForUser | Select-Object -ExpandProperty AuditData | ConvertFrom-Json

$ConvertedOutput | Select-Object CreationTime,UserId,Operation,Workload,ObjectID,SiteUrl,SourceFileName,ClientIP,UserAgent | Export-Csv $OutputFile -NoTypeInformation -Append
}
 
Remove-PSSession $session 

4.   Sample CSV output

5. Please also go thru following articles to better understand the Audit log concept and detailed properties that can be retrieved:

  https://support.office.com/en-us/article/Search-the-audit-log-in-the-Office-365-Security-Compliance-Center-0d4d0f35-390b-4518-800e-0c7ec95e946c?ui=en-US&rs=en-US&ad=US

https://technet.microsoft.com/en-us/library/mt238501(v=exchg.160).aspx

https://support.office.com/en-us/article/Detailed-properties-in-the-Office-365-audit-log-ce004100-9e7f-443e-942b-9b04098fcfc3