In light of some recent events, I thought I’d build on another project I have going on and drop this quick script here for talking to the Office 365 Service Communications API.
The Office 365 Service Communications API is a REST-based interface to retrieve data from the service. You can read more about access it here: https://docs.microsoft.com/en-us/office/office-365-management-api/office-365-service-communications-api-reference.
So, in order to achieve a result for customer with a project a few months ago, I started tinkering with the idea of being able to retrieve statuses via Invoke-WebRequest in PowerShell. In order to do this, you’ll need to create an app registration and grant it the appropriate permissions.
The App ID and Client Secret parts might be a little foreign to some people, so we’ll go through those steps here. It’s going to involve three parts:
- Creating an App registration
- Creating a client secret
- Setting permissions
Creating an app registration
- Log into the Azure Portal (https://portal.azure.com) and search for Azure Active Directory. Or, if you’re already there from the last prerequisite step, don’t do anything.
- Under Manage, select App registrations.
- Click + New registration.
- Configure the app:
– Enter a name for the application.
– Ensure the Accounts in this organizational directory only (first) radio button is selected.
– Under Redirect URI, select Web in the drop-down and enter
http://localhostin the text box.
- Click Register.
- Click the copy link next to Application (client) ID. Copy the value and paste it in your scratch pad (be sure to identify that it’s the client ID).
Next, we’ll create the secret.
Creating a client secret
- Under Manage, select Certificates & secrets.
- Click + New client secret.
- Enter a description for this particular client secret and select an expiration date.
- Click Add.
- Copy the value for the newly created client secret. Once you navigate from this page, you won’t be able to see the value anymore and will have to start over at step 8.
Now that you have an app id and a client secret, you need to grant the app id permissions to see certain data inside the tenant. For the purposes of this Flow, you need to be able to read content from the Message Center.
- Under the Manage section of the app registration, select API permissions.
- Click + Add a permission.
- Select the Office 365 Management APIs tile.
- Select the Delegated permissions box select Add permissions at the bottom (you can deselect the ActivityFeed.ReadDlp and ActivityFeed.Read if you’d like, since we’re not really going to be using it for this explicit purpose).
- Click Add permissions.
- Repeat steps 2-5, selecting Application permissions.
- Select Grant admin consent for <tenant>.
- Click Yes to confirm granting consent.
Now, with the app registration done and permissions set, you can use the script!
The best place to get the script is from the PowerShell Gallery (https://www.powershellgallery.com/packages/Get-Office365ServiceAPIStatus/).
It supports all four service endpoint types defined by the API (Services, CurrentStatus, HistoricalStatus, Messages). The default is CurrentStatus, but you can use any of them. Here are some examples:
Current status returns the workload display name, status display name, the time the status was updated.
The Services parameter returns all of the services you have subscribed to in your tenant.
This parameter can be used to return the the historical statuses for the past 7 days for each service.
The Messages parameter returns the last n message center postings with basic information including the title, affected workload, time/date, severity, and message type.
Just wanted to reiterate this–when using the
ClientID parameter, be sure to use the client ID of your App Registration.
ClientSecret is the value that gets hidden after you create the specific client ID/client secret entry. Since the ClientSecret is only ever displayed when you create it, you’ll want to store it in a safe place so you can use it when you need to. You could, alternatively, update the script parameters directly with those values (but I wouldn’t necessarily recommend that).
It’s obviously a rough script, but it gives you some ideas of what you might be able to achieve.