Exchange Audit Logs

-->

Security, compliance, and auditing have become a top priority for IT administrators in today’s world. Microsoft 365 has several built-in capabilities to help organizations manage security, compliance, and auditing. In particular, unified audit logging can help you investigate security incidents and compliance issues. You can retrieve audit logs by using the following methods:

  • Audit log search is turned on by default for Microsoft 365 and Office 365 enterprise organizations.

  • To verify that audit log search is turned on, you can run the following command in Exchange Online PowerShell:.

If you need to retrieve audit logs on a regular basis, you should consider a solution that uses the Office 365 Management Activity API because it that can provide large organizations with the scalability and performance to retrieve millions of audit records on an ongoing basis. Using the audit log search tool in Microsoft 365 compliance center is a good way to quickly find audit records for specific operations that occur in shorter time range. Using longer time ranges in the audit log search tool, especially for large organizations, might return too many records to easily manage or export.

When there are situations where you need to manually retrieve auditing data for a specific investigation or incident, particularly for longer date ranges in larger organizations, using the Search-UnifiedAuditLog cmdlet may be the best option. This article includes a PowerShell script that uses the cmdlet that can retrieve 50,000 audit records (each time you run the cmdlet) and then export them to a CSV file that you can format using Power Query in Excel to help with your review. Using the script in this article also minimizes the chance that large audit log searches will time out in the service.

Before you run the script

  • The value of True for the UnifiedAuditLogIngestionEnabled property indicates that audit log search is turned on. For more information, see Turn audit log search on or off. You have to be assigned the View-Only Audit Logs or Audit Logs role in Exchange Online to search the audit log.

    By default, these roles are assigned to the Compliance Management and Organization Management role groups on the Permissions page in the Exchange admin center.

  • Global administrators in Office 365 and Microsoft 365 are automatically added as members of the Organization Management role group in Exchange Online. To give a user the ability to search the audit log with the minimum level of privileges, you can create a custom role group in Exchange Online, add the View-Only Audit Logs or Audit Logs role, and then add the user as a member of the new role group.

  • For more information, see Manage role groups in Exchange Online. If you assign a user the View-Only Audit Logs or Audit Logs role on the Permissions page in the Microsoft 365 compliance center, they won't be able to search the audit log. You have to assign the permissions in Exchange Online.

  • This is because the underlying cmdlet used to search the audit log is an Exchange Online cmdlet. When an audited activity is performed by a user or admin, an audit record is generated and stored in the audit log for your organization. The length of time that an audit record is retained (and searchable in the audit log) depends on your Office 365 or Microsoft 365 Enterprise subscription, and specifically the type of the license that is assigned to specific users. For users assigned an Office 365 E5 or Microsoft 365 E5 license (or users with a Microsoft 365 E5 Compliance or Microsoft 365 E5 eDiscovery and Audit add-on license), audit records for Azure Active Directory, Exchange, and SharePoint activity are retained for one year by default.

Step 1: Connect to Exchange Online PowerShell

The first step is to connect to Exchange Online PowerShell. You can connect using modern authentication or with multifactor authentication (MFA). For step-by-step instructions, see Connect to Exchange Online PowerShell.

Step 2: Modify and run the script to retrieve audit records

After you've connected to Exchange Online PowerShell, the next step is to create, modify, and run the script to retrieve the auditing data. The first seven lines in the audit log search script contain the following variables that you can modify to configure your search. See the table in step 2 for a description of these variables.

  1. Organizations can also create audit log retention policies to retain audit records for activities in other services for up to one year.

  2. For more information, see Manage audit log retention policies. If your organization participated in the private preview program for the one-year retention of audit records, the retention duration for audit records that were generated before the general availability rollout date will not be reset.


VariableSample valueDescription
$logFile"d:\temp\AuditSearchLog.txt"Specifies the name and location for the log file that contains information about the progress of the audit log search performed by the script. The script writes UTC timestamps to the log file.
$outputFile"d:\temp\AuditRecords.csv"Specifies the name and location of the CSV file that contains the audit records returned by the script.
[DateTime]$start and [DateTime]$end[DateTime]::UtcNow.AddDays(-1)
[DateTime]::UtcNow
Specifies the date range for the audit log search. The script will return records for audit activities that occurred within the specified date range. For example, to return activities performed in January 2021, you can use a start date of "2021-01-01" and an end date of "2021-01-31" (be sure to surround the values in double-quotation marks) The sample value in the script returns records for activities performed in the previous 24 hours. If you don't include a timestamp in the value, the default timestamp is 12:00 AM (midnight) on the specified date.
$record"AzureActiveDirectory"Specifies the record type of the audit activities (also called operations) to search for. This property indicates the service or feature that an activity was triggered in. For a list of record types that you can use for this variable, see Audit log record type. You can use the record type name or ENUM value.
Tip: To return audit records for all record types, use the value $null (without double-quotations marks).
$resultSize5000Specifies the number of results returned each time the Search-UnifiedAuditLog cmdlet is called by the script (called a result set). The value of 5,000 is the maximum value supported by the cmdlet. Leave this value as-is.
$intervalMinutes60To help overcome the limit of 5000 records returned, this variable takes the data range you specified and slices it up into smaller time intervals. Now each interval, not the entire date range, is subject to the 5000 record output limit of the command. The default value of 5000 records per 60-minute interval within the date range should be sufficient for most organizations. But, if the script returns an error that says, maximum results limitation reached, decrease the time interval (for example, to 30 minutes or even 15 minutes) and rerun the script.

Most of the variables listed in the previous table correspond to parameters for the Search-UnifiedAuditLog cmdlet. For more information about these parameters, see Search-UnifiedAuditLog.

  1. For users assigned any other (non-E5) Office 365 or Microsoft 365 license, audit records are retained for 90 days.

  2. For a list of Office 365 and Microsoft 365 subscriptions that support unified audit logging, see the security and compliance center service description.

The script displays progress messages while it's running. After the script is finished running, it creates the log file and the CSV file that contains the audit records and saves them to the folders defined by the $logFile and $outputFile variables.

Even when mailbox auditing on by default is turned on, you might notice that mailbox audit events for some users aren't found in audit log searches in the Microsoft 365 compliance center or via the Office 365 Management Activity API.

For more information, see More information about mailbox audit logging. If you want to turn off audit log search for your organization, you can run the following command in remote PowerShell connected to your Exchange Online organization:. To turn on audit search again, you can run the following command in Exchange Online PowerShell:. For more information, see Turn off audit log search. As previously stated, the underlying cmdlet used to search the audit log is an Exchange Online cmdlet, which is Search-UnifiedAuditLog.

Step 3: Format and view the audit records

After you've run the script and exported the audit records to a CSV file, you may want to format the CSV to make easier to review and analyze the audit records. One way to do this is to the Power Query JSON transform feature in Excel to split each property in the JSON object in the AuditData column into its own column. For step-by-step instructions, see "Step 2: Format the exported audit log using the Power Query Editor" in Export, configure, and view audit log records.

Comments are closed.