This is part two of a 2-part blog post.
- Walkthrough Setting up WebHook for O365 Audit Logs
- Dive into the code for O365 Audit Log webhooks to see how it works – (This Post)
The previous blog post showed how to get you up and running with O365 Audit logs and webhooks. In this blog post I’m going to show and explain parts of the code that ties everything together.
The full code can be found at my Github repo https://github.com/pmatthews05/O365AuditWebHook
PowerShell to initialize the Webhook to the Audit logs
Run on one line.
From inside the PowerShell folder (.\O365AuditWebhook\PowerShell) there is a PowerShell file called Set-AuditLogs.ps1 This PowerShell file Starts a subscription to the given Audit Content Type. This is done by calling:
The above call is a POST call and uses the ClientID and Secret to authenticate against the tenant. The body is a Json object
- authId – Optional string that will be included as the WebHook-AuthID header in notifiations sent to the webhook as a means of identifying and authorizing the source of the request to the webhook
- expiration – Optional datetime that indicates the datatime after which notifications should no longer be sent to the webhook. By leaving it empty, indicates the subscription will be active for the next 180 days.
- address – Required HTTPS endpoint that can receive notifications. A test message will be sent to the webhook to validate the webhook before creating the subscription.
When the /start operation is called, the webhook URL specified in the address will be sent a validation notification to validate that an active listener can accept and process notifications.
The Azure Function AuditWebhook found in the O365AuditWebhook.cs file has two parts to it.
The first part, as shown above, handles the validation. It looks for a validation code within the content, and if found it response back with a 200 status (OK) and includes the validation code.
If an OK is not received back, then the webhook will not be added and the subscription will remain unchanged.
The second part of the AuditWebhook Azure function is explained in the next section.
Webhook handling O365 notifications
After the initial validation, notifications will be sent to the webhook as the content logs become available.
From the first part of the AuditWebHook Azure Function, notifications do not have the validationCode, this allows us to determine that notifications have been sent, instead of a new subscription.
The content of these notifications contains an array of one or more JSON objects that represent the available content blobs.
On line 5 of the above code, show where I handle the content of deserialize json object (notifications) to a list of AuditContentEntity.
The notification/AuditContentEntity contains the following:
- tenantId –
The GUID of the tenant to which the content belongs
- clientId – The GUID of your application that created the subscription
- contentType – Indicates the content type
- contentId – An opaque string that uniquely identifies the content
- contentUri – The URL to use when retrieving the content
- contentCreated – The datetime when the content was made available
- contentExpiration – The datetime after which the content will no longer be available for retrieval.
At this point you do not have any log information, you just have a collection of contentUri which when called will provide you with the logs. To ensure that the webhook response quickly so that it can continue to handle incoming requests, we place the contentUri, contentType, and TenantId onto an Azure Storage Queue. This allows a different Azure function to handle getting the actual logs.
Lines 9-16 will set up the storage queue if it doesn’t exist.
Lines 19-26 prepares my queue object and serialize it to a json string.
Line 28 adds the message to the Azure Storage Queue.
Once all notifications/AuditContentEntity have been processed, a 200 status (OK) is passed back. The subscription that calls our webhook is waiting for an OK response. If it encounters failure, it has a built in retry mechanism that will exponentially increase the time between retries. If the subscription continues to receive failure response, the subscription can disable the webhook and stop sending notifications. The subscription will need to be started again to re-enable the disabled webook.
Processing the Storage Queue AuditContentUri
As items are put on the Storage Queue the Azure Function AuditContentUri found in the O365AuditWebhook.cs file fires.
First you need an authorization token to read the audit logs, we do this with AcquireTokenForApplication method. This uses the Tenant Name, ClientId and Secret that is stored within your Azure configurations. See ‘How to acquire token for application?’ below.
It grabs the ContentUri and then goes into a do loop. This is because the logs that come back, if it is a very busy tenant, not all the logs will be returned, and there will be a NextPageUri value in the header of the response to allow you to obtain the next page of logs.
Line 7 – This adds your tenantID to the end of the URI as a PublisherIdentifier. This parameter is used for throttling the request rate. Make sure this parameter is specified in all issued requests to get a dedicated quota. All requests received without this parameter will share the same quota. The IF statement ensures it is added to the end of the URI correctly.
Line 9 – This calls the ContentUri and gets a results and request headers. You can see the file .\O365AuditWebHook\AuditWebHook\Utilities\RestAPI.cs
The Method GetRestDataAsync is very similar to the GetRestData call you find within PNP Core code. Creates a HttpWebRequest, passing in Authorization Token, and calling the ContentUri. Only difference in my code is that I’m grabbing the response.Headers to find out if there are additional logs, and passes them back with the results.
Line 10 – This parse the results into a JArray. (Json Array object). Here you can manipulate what comes back. For example, instead of grabbing all results and then displaying them out, you can query the results for a particular log type.
In the example code below, this would be using the Audit.General logs, and it will grab any logs that are of RecordType 25 (Indicates Microsoft Teams event) where the operation is creating a new channel, and the Channel type is Private. I then convert the JArray to an object list of AuditGeneralEntity.
For further details about properties of the audit logs can be found here: https://docs.microsoft.com/en-us/microsoft-365/compliance/detailed-properties-in-the-office-365-audit-log
Line 14 – Logs out an individual log entry, this is in a json format. Different schema’s can be found here: https://docs.microsoft.com/en-gb/office/office-365-management-api/office-365-management-activity-api-schema
Line 17 – If there are any additional pages, then this will return a value, and the loop will loop until no more pages are found.
How to acquire token for application?
In the previous section, I called a method AcquireTokenForApplication. This is a helper class and method that I use quite often, when I need to obtain an AccessToken. You can find this in the repo at .\O365AuditWebHook\AuditWebHook\Utilities\AuthenticationHelper.cs. This solution has a cut down version of the helper class I use. It is cut down as it just gets an access token for Audit Logs using AppId and Secret.
Above is a snippet, as you can see it is wrapped in a retry method in case there is throttling.
PowerShell to stop the Audit logs
Within the PowerShell folder I have also included a file called Remove-AuditLogs.ps1
Run on one line.
This works exactly like the Set-AuditLogs.ps1 file except it calls the /stop endpoint:
Once the subscription is stopped, no notifications will be sent to your webhook, and you will not be able to retrieve available content. Please note, if you decide to start the subscription again later using the Set-AuditLogs.ps1 you will not receive any content that was available between the stop and start time of the subscription.
This is quite a heavy post; I hope it has helped you in some way. It is just a starter, as you will probably want to do something with the logs instead of just writing them out to the Azure Logs. Maybe capturing a given process to then implement some logic to react. You might also want to put different Audit content types ContentUri onto different Azure Storage queue, so that different Azure Functions can process the ContentUri.