Zum Inhalt

Switch to UnifiedAuditLog from MailboxAuditLog (and AdminAuditLog)

Microsoft is going to retire Audit Log cmdlets from the 'Exchange Online PowerShell' module starting from September 2024. Instead, they recommend using the Unified Audit Log (UAL) for auditing.

  • MailboxAuditLog: The Mailbox Audit Log cmdlets will have a separate deprecation date, which will be announced early next year.
  • AdminAuditLog: Two Admin Audit Log cmdlets, Search-AdminAuditLog and New-AdminAuditLog (New-AdminAuditLogSearch), will retire on September 15, 2024. It's recommended to use Search-UnifiedAuditLog instead.

Overview of Cmdlets

  • Search-MailboxAuditLog is still unannounced for an updated deprecation date? Correct, there is no known deprecation date.
  • Search-AdminAuditLog will be removed in September this year.
Cmdlet Module Deprecation
Search-AdminAuditLog, New-AdminAuditLogSearch ExchangeOnlineManagement Yes (EOL1: April 2024 > Sept 2024)
Search-MailboxAuditLog, New-MailboxAuditLogSearch ExchangeOnlineManagement Yes (EOL1: April 2024 > TBD)
Search-UnifiedAuditLog ExchangeOnlineManagement No

How to use UnifiedAuditLog

The Unified Audit Log is stored for 180 days2 and the usage of this new cmdlet has slightly changed in terms of available Attributes and generated output.

The default retention period for Audit (Standard) has changed from 90 days to 180 days. Audit (Standard) logs generated before October 17, 2023 are retained for 90 days. Audit (Standard) logs generated on or after October 17, 2023 follow the new default retention of 180 days.

Preparation (PowerShell)

To begin using 'ExchangeOnlineManagement PowerShell' and accessing the 'Unified Audit Log,' you need to follow these preparatory steps. These cmdlets will allow you to verify whether auditing is enabled on the tenant:

1
2
3
4
5
# --- Preparation
# Install-Module -Name ExchangeOnlineManagement
Connect-ExchangeOnline
Get-AdminAuditLogConfig | Format-List UnifiedAuditLogIngestionEnabled
Set-AdminAuditLogConfig -UnifiedAuditLogIngestionEnabled $true

Audit Logs Types

There are different types of Logs which are being tracked for Exchange:

LogType (Area) RecordType Description
MailboxAuditLog ExchangeItem Events from an Exchange mailbox audit log for actions that are performed on a single item, such as creating or receiving an email message.
MailboxAuditLog ExchangeItemGroup Events from an Exchange mailbox audit log for actions that can be performed on multiple items, such as moving or deleted one or more email messages.
MailboxAuditLog ExchangeItemAggregated Events related to the MailItemsAccessed mailbox auditing action.
AdminAuditLog ExchangeAdmin Events from the Exchange admin audit log.

Solution A for UserMailbox

In the previous MailboxAuditLog, you could request multiple log types simultaneously and receive a consolidated output. However, from what I understand, this is no longer possible. Now, you must request either all log types or one at a time. Additionally, the default output is limited to 100 entries, which typically requires adjustment. Please make sure that Auditing has earlier been Enabled on the Mailbox you request.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
#$username = "usermailbox@contoso.com"
#Get-Mailbox $username | Format-List *Audit*, UserPrincipalName

# --- Legacy, UserMailbox & SharedMailbox
Search-MailboxAuditLog
Search-MailboxAuditLog -Identity $username -LogonTypes Admin,Delegate -StartDate 1/1/2024 -EndDate 12/31/2024 -ResultSize 2000


# --- New, UserMailbox - Basic
Search-UnifiedAuditLog
#Search-UnifiedAuditLog -StartDate (Get-Date).AddDays(-30) -EndDate (Get-Date) 
Search-UnifiedAuditLog -UserIds $username -StartDate (Get-Date).AddDays(-30) -EndDate (Get-Date) | Out-GridView

# --- New, UserMailbox  - Advanced
$start = (Get-Date).AddDays(-5)
#$end = (Get-Date).AddDays(-1)
$end = (Get-Date)

$logs = Search-UnifiedAuditLog -RecordType ExchangeItem -UserIds $username -StartDate $start -EndDate $end -ResultSize 1000 ; $logs.Count
$logs | Group RecordType | Sort Count
$logs | Group UserIds | Sort Count
$logs | Group Operations | Sort Count

$auditData = New-Object System.Collections.ArrayList; 
#Search-UnifiedAuditLog -StartDate $start -EndDate $end -OutVariable +auditData | Out-Null
$logs = Search-UnifiedAuditLog -RecordType ExchangeItem -StartDate $start -EndDate $end -OutVariable +auditData -ResultSize 1000 ; $logs.Count
$logs = Search-UnifiedAuditLog -RecordType ExchangeItemGroup -StartDate $start -EndDate $end -OutVariable +auditData -ResultSize 1000 ; $logs.Count
$logs = Search-UnifiedAuditLog -RecordType ExchangeItemAggregated -StartDate $start -EndDate $end -OutVariable +auditData -ResultSize 1000 ; $logs.Count
$auditData | Group RecordType | Sort Count
$auditData | Group UserIds | Sort Count
$auditData | Group Operations | Sort Count

Solution B for SharedMailbox

Since the transition to the UnifiedAuditLog, I've noticed that Shared Mailboxes are sometimes excluded from the output. To retrieve their data, you need to use the 'FreeText' attribute along with the corresponding 'ExchangeGuid'. It could be useful to find out whether the '-UserIds' parameter works for Shared Mailboxes that are licensed (active archive).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
#$username = "sharedmailbox@contoso.com"
#Get-Mailbox $username -RecipientTypeDetails SharedMailbox | Format-List *Audit*, UserPrincipalName

# --- Legacy, UserMailbox & SharedMailbox
Search-MailboxAuditLog -Identity $username
$logs = Search-MailboxAuditLog -Identity $username -LogonTypes Admin,Delegate,Owner -StartDate $start -EndDate $end -ResultSize 1000 -ShowDetails
$logs | ft Operation, LogonType, *FolderPathName, SourceItemSubjectsList, Last*
$logs | Group-Object Operation, OperationResult


# --- New, SharedMailbox
#$logs_shared = Search-UnifiedAuditLog -UserIds $username -StartDate $start -EndDate $end -ResultSize 2000; $logs_share.count # 0x Entries
$logs_shared = Search-UnifiedAuditLog -FreeText (Get-Mailbox $username).ExchangeGuid -StartDate $start -EndDate $end -ResultSize 2000; $logs_shared.count 
$logs_shared | Group-Object RecordType
#$logs_shared | Select-Object -First 200 | Out-GridView
$logs_shared_json = ($logs_shared.AuditData | ConvertFrom-Json)
$logs_shared_json | Group-Object Operation | ft -AutoSize

Solution C for ExchangeAdmin

The process for retrieving Admin Logs follows a similar schema to that of user logs. The primary difference is that you need to specify the appropriate log type. By changing the log type, you should be able to view all administrative actions performed through the Exchange Admin Center or Exchange PowerShell. This approach ensures comprehensive visibility into any modifications or configurations carried out by administrators.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# --- Legacy
Search-AdminAuditLog
Search-AdminAuditLog -ExternalAccess $true -StartDate 01/01/2024 -EndDate 12/31/2024

# --- New, Exchange Admin Logs
#Search-UnifiedAuditLog -RecordType ExchangeAdmin -StartDate (Get-Date).AddDays(-30) -EndDate (Get-Date)
Search-UnifiedAuditLog -RecordType ExchangeAdmin -StartDate (Get-Date).AddDays(-30) -EndDate (Get-Date) | Out-GridView
$logs_admin = Search-UnifiedAuditLog -RecordType ExchangeAdmin -StartDate (Get-Date).AddDays(-30) -EndDate (Get-Date); $logs_admin.count
#$logs_admin = Search-UnifiedAuditLog -Operations Set-Mailbox -StartDate (Get-Date).AddDays(-30) -EndDate (Get-Date); $logs_admin.count
#$logs_admin | Out-GridView
$logs_admin_json = ($logs_admin.AuditData | ConvertFrom-Json)
$logs_admin_json | Group-Object Operation | ft -AutoSize
#$logs_admin_json | Out-GridView

Summary

I see the reason in combining this log types and probably also simplify background infrastructure to provide long-term storage capabilities. For me, it still feels a bit like data engineering when searching, and I wish to see more attributes to filter and less JSON Objects inside of PowerShell. Wish you all a good day and success in finding your entries.

References:

  1. End of life (EOL), cmdlet not available anymore ↩↩

  2. Default audit log retention policy ↩