Utilizing the Workplace 365 Administration Exercise API from Powershell to audit Change and Workplace365

Utilizing the Workplace 365 Administration Exercise API from Powershell to audit Change and Workplace365 The Workplace 365 Administration Exercise API is a REST endpoint that can be utilized to entry audit occasions from person, admin, system, and coverage actions and occasions in Azure and Workplace365 workloads (its been round for some time first appeared in 2015 in preview). Inside Workplace365 there are lots of methods of accessing one of these info the Major UI lately for auditing is the Unified Audit logs accessible within the Workplace365 Portal https://assist.workplace.com/en-us/article/Search-the-audit-log-in-the-Workplace-365-Safety-Compliance-Heart-0d4d0f35-390b-4518-800e-0c7ec95e946c#PickTab=HowTo

The benefit of utilizing the Administration Exercise API over the portal is that  lets you create extra tailor-made reporting by accessing the uncooked knowledge over a time period (so writing your personal person pattern reporting) utilizing a scalable API like REST (which in case you have loads of knowledge to question is superior to utilizing WinRM options utilizing one thing just like the Change Administration Shell cmdlets). It additionally consists of WebHooks interfaces that can be utilized to set off different workloads to course of specific Audit occasions on a seamless foundation. (Though you need to notice the documentation states that this API is not meant for use for actual time alerting as there are different Microsoft supplied endpoint and companies to offer this performance).
The way it works

The Administration Exercise API makes use of a subscription based mostly strategy, the mechanics are comparatively easy eg 

  • You create a Subscription for the Workload you need to entry the Audit occasion for.(eg Change)
  • The backend then produces contentblobs that are aggregates of these audit logs after which makes them accessible to entry. If in case you have registered a WebHook to your subscription then your endpoint shall be notified that there’s a new ContentBlob accessible so that you can course of.
  • When you now not require the subscription you may then Cease that subscription.

One level to notice is that the Administration Exercise API does not really allow auditing for any of the workloads it simply make accessible knowledge from the Auditing that’s already enabled. Eg as an illustration Change Mailbox Auditing is not turned on by default so in case you did the above course of to create a subscription for Change you’ll by no means see any ContentBlobs generated for Mailbox Auditing occasions until you first went and enabled auditing on the Mailboxes you want to audit https://assist.workplace.com/en-us/article/enable-mailbox-auditing-in-office-365-aaca8987-5b62-458b-9882-c28476a66918 after which these occasions could be accessible inside your subscription. This is identical for different workload as effectively, some workloads like AzureAD have some auditing enabled by default however you need to all the time verify your auditing configuration to be sure to have turned on the actual auditing setting for the actual workload your occupied with earlier than utilizing this API.


With the Administration Exercise API the subscription mechanism has the flexibility to ship a WebHook notification to any Webhook endpoint you configure. One simple to make use of webhook instance is Azure RunBooks https://docs.microsoft.com/en-us/azure/automation/automation-webhooks so utilizing one thing like this your subscription may set off a RunBook which might then course of the ContentBlob that has simply been made accessible and apply any Logic or customized report you want. The great factor with RunBooks is all of the underlying service elements of the code are performed for you and you may simply plug in your customized script to do what you want.


The stipulations for this API is that you must have an Utility registration see created that has been  given the oAuth Grants to entry the API. You have to generate your entry tokens for the useful resource url handle.workplace.com (so for instance you may’t use a token you will have generated in opposition to the Graph endpoint you must particularly request this ResourceURL). The very last thing is the Account you then use to the entry the API must have rights to the Audit knowledge. (In case you select to make use of certificates authentication and a daemon sort app this might get the rights via the totally different oAuth Grants for purposes).

Placing it to make use of

A extremely straight ahead manner of utilizing this API from PowerShell is to utilize Invoke-WebRequest and there’s a good doc right here on doing this https://msdn.microsoft.com/en-us/office-365/troubleshooting-the-office-365-management-activity-api . One other simpler and extra useful strategy is to make use of my Exch-REST module which is on the market from the PowerShell Gallery https://www.powershellgallery.com/packages/Exch-Relaxation and GitHub https://github.com/gscales/Exch-Relaxation which now has some cmdlets and plumbing to allow use of this API. The module can now deal with caching tokens from a number of sources (eg the Graph and Administration API) so you may then mix operations from each API’s which is the place you may then begin to construct extra highly effective tailor-made studies. Eg in case your processing the Content material Blobs for specific Mailboxes and also you need extra details about that mailbox to incorporate in a report you should use the Graph to simply entry that. Or in case you wished to verify on a Message that was deleted by a person to see if it had any attachments that would include delicate content material you may use the Graph API to achieve into the Mailbox and entry the deleted message from the Recoverable Objects folders and so on.

Utilizing Exch-REST to create and entry subscription content material

Connecting and Producing the Entry Token 

To Join and generate an Accesstoken to make use of in opposition to the Administration API use Join-EXRManagementAPI

I’ve created a default app registration that you should use for testing (quantity 5) that simply has entry to the Administration API Oauth Grants however would advocate as normally that you simply create your personal App registration  see so that you management what rights the code could have. One different necessary factor to notice is the subscription are per appid, so in case you create a subscription with say the above AppId after which create your personal ApplicationId at a later level and use that you simply will not be capable of see/view/cease the subscriptions you created with the pervious appId until your login utilizing that pervious ApplicationId.

Upon getting a token you may then use the Administration API cmdlets for instance to point out the present subscriptions use Get-EXRMSubscriptions

If that is the primary time you’re utilizing this API it can simply present a clean listing. To create a brand new subscription use the New-EXRMSubscription cmdlet with the swap for the workload you need to use eg to create a New AzureADSubscription use the -AzureAd swap

different workload swap are

-Common (different workloads like Groups are included right here)

If you wish to use WebHooks there are particular parameters for this that lets you specify the mandatory Webhook particulars.

Upon getting created the subscription the content material blobs do not get created right away the documentation say that this can take about 6-24 hours for content material to begin to develop into accessible. As soon as they’re accessible you may entry them utilizing the Get-EXRMSubscriptionContent cmdlet eg to get the Change content material for the final 24 hours

Get-EXRMSubscriptionContent -Change -StartTime (Get-Date).AddDays(-1) -EndTime (Get-Date)

The information you get again for this operation incorporates the contenturi of the blob you can then entry utilizing the SubscriptionContentBlob operation. I’ve a separate cmdlet that can be utilized to retrieve the blob eg

Get-EXRMSubscriptionContentBlob -ContentURI https://handle.workplace.com...

Nonetheless I discovered the useability of doing it this solution to not be so nice so I included a swap within the Get-EXRMSubscriptionContent cmdlet so you may specify to return the contentblobs eg

Get-EXRMSubscriptionContent -Change -StartTime (Get-Date).AddDays(-1) -EndTime (Get-Date) -returnContentBlobs

eg this can the return the contentblob with every content material entry

You possibly can then course of the Contentblob property and the info inside anyway you want, right here is one instance that produces a Consumer report utilizing the consumer agent knowledge for the final 24hours

$Final24Outcomes = Get-EXRMSubscriptionContent -Change -StartTime (Get-Date).AddDays(-1) -EndTime (Get-Date) -returnContentBlobs

$BlobEntries = foreach($ContentEntry in $Final24Outcomes){$ContentEntry.ContentBlob}

$BlobEntries | The place-Object{$_.ClientInfoString -ne $null} | choose  CreationTime,Operation,ClientInfoString,Use
rId | fl

Or you may simply have a look at issues just like the MoveToDeletedItems occasions and get extra info

As soon as your completed with a Subscription and also you now not need to course of content material blobs you may cease the subscription utilizing Invoke-EXRMStopSubscription eg to cease the Change Subscription use

Invoke-EXRMStopSubscription  -Change

The mixtures of what you are able to do are simply restricted to your personal creativeness or specific audit bucket you must fill. If in case you have want for a developer/scripter or simply somebody for to assist out for something change/workplace365 associated I am accessible to tackle work for the time being so please contact me at gscales@msgdevelop.com (nothing too huge or small). I would even be occupied with listening to from any firms that need to sponsor open supply tasks round Change and Workplace365 improvement.

The Exch-REST module is on the market from the PowerShell Gallery https://www.powershellgallery.com/packages/Exch-Relaxation and GitHub https://github.com/gscales/Exch-Relaxation

Leave a Reply