Introduction

Current version: 1.0.1

This script demonstrates how to use the Office 365 Management API to download audit logs.  The script can also be used to register an application in AzureAD (which is required to collect your audit logs).

Description

To be able to collect logs, you first need to register an application.  To do this, you'll need the global administrator log-in for your tenant, and you can then run the script using these parameters:

.\Test-ManagementActivityAPI.ps1 -RegisterAzureApplication -AzureApplicationName "ManagementAPIData"

You may be prompted to install modules (the script requires Azure AD modules, and will try to install them if not already present).  Assuming the AzureAD modules are installed successfully, you'll then be prompted to log-on to the tenant.  Once done, the script will register the application and display the application Id and the secret key  Make a note of both of these as you'll need them for all other script functions (along with your tenant Id, which will also be shown).

You should be able to use the information provided here in third party solutions also (e.g. SIEM), but you'd need to check with the developers of the solution.

Once the application is registered, you need to start collecting events.  Note that this takes some time, and once started you won't be able to retrieve the events for 24 hours.  To start event collection:

.\Test-ManagementActivityAPI.ps1 -Start -AppId "<appid>" -TenantId "<tenantid>" -AppSecretKey "xx"

AppId, TenantId, and secret key are all as displayed when you registered the application.

To retrieve data from the audit logs, you can use the following (which will retrieve all logs collected in the previous 24 hours):

.\Test-ManagementActivityAPI.ps1 -RetrieveContent -SaveContentPath "c:\Temp\API Data" -ListContentDate $([DateTime]::Now.AddDays(-1)) -AppId "<appid>" -TenantId "<tenantid" -AppSecretKey "xx"

To collect all logs from a tenant, you could schedule the above command to run once daily (in my test tenant, I run this every morning at 7am to collect the logs).  The script retrieves the audit logs and saves them as text files in the specified directory.  From those, you could read and ingest into a database if you wanted (you'd need to do something like that to make use of the logs).

Parameters

-AppId The application Id of the Azure application (generated by Azure when the application is registered).
-AppSecretKey Secret key for the application (generated at registration, or via the Azure Portal).
-AppAuthCertificate Not currently implemented.
-AppRedirectURI Redirect URI for the app as registered in Azure.  Can be left at the default (http://localhost/TestManagementActivityAPI)
-TenantId This is the Id of the tenant that the logs are retrieved from.  This can be obtained from the Azure Portal, or the script will show it when used to register the application.
-PublisherId The tenant Id of the publisher.  Usually, this will be your tenant Id and can be ignored.
-Start Starts a subscription (i.e. triggers the API to start collecting logs).
-WebhookAddress Webhooks are no longer recommended, but this would be the endpoint to which audit logs are sent.
-ContentType The audit logs to be retrieved.  Defaults to Exchange audit logs.
-Stop Stops a subscription.
-List Lists currently registered subscriptions.
-ListContent Lists available content.
-RetrieveContent Retrieves the available content (same as -ListContent, but will then download the content listed).
-SaveContentPath The path in which audit logs will be saved (as text files).
-ListContentDate The date for which content will be retrieved (this script always retrieves 24 hours worth of data starting with this date/time).
-RegisterAzureApplication Used to register the application in Azure.
-AzureApplicationName The name of the application to register in Azure.
-AzureApplicationRequiredPermissions Required permissions for the application.  By default, the script requests all the permissions needed to retrieve all logs.  You can limit it to specific audit log sources if required.
-LogFile Script activity will be logged to this file.