Utilizing the Workplace365/Alternate 2016 REST API to entry Mailbox knowledge utilizing PowerShell half 1

In comparison with EWS the place there was little or no up entrance configuration essential to get going (eg in most case simply provide a username and password) for the REST API’s there’s a little bit of configuration that must be performed.

To make use of the brand new REST endpoint it is advisable to use oAuth authentication which suggests as a substitute of a username and password being included as a header which every request to the server like in Primary Authentication you utilize an Entry Token which is barely legitimate for an hour. A Refresh Token can be utilized to resume the Entry Token when it expires. Tokens supply a giant safety benefit over utilizing a UserName and Password however nonetheless ought to be handled as in the event that they the place a username and password with reference to storage and entry as they will nonetheless be exploited in the identical method. That is an excessive simplification of the oAuth, there is a few good documentation sources however watch out of people who talk about Fashionable Authentication and the ADAL library as they have a tendency to summary away some the actual technical aspect of understanding what’s taking place with Token Auth. Personally I like https://docs.microsoft.com/en-gb/azure/active-directory/develop/active-directory-authentication-scenarios and https://msdn.microsoft.com/en-us/office-365/get-started-with-office-365-management-apis as these look extra on the underlying method the protocols work.

To make use of oAuth to authenticate it is advisable to create an Software registration (which supplies you the clientId) to make use of in your scripts or authorize any individual else’s (which would not be really useful).  There are many good stroll throughs on creating app registrations utilizing the Azure console this one is sort of good https://github.com/jasonjoh/workplace365-azure-guides/blob/grasp/RegisterAnAppInAzure.md . For scripting typically you need to create a Native App registration and use the Out of Band Name-back urn:ietf:wg:oauth:2.0:oob . One of many large benefits of utilizing oAuth with the brand new REST interfaces is the authentication scopes which let you limit an software/script to only with the ability to entry the assets you need. Eg if this app goes to simply entry contacts knowledge you then simply allow the authentication scope that enables entry to contacts knowledge with out permits entry to another Mailbox objects.

Authenticating as a Person or Software

In EWS and MAPI authentication is all the time performed within the context of the Person if you wish to entry a Mailbox different then that of safety context you might be utilizing then Delegation would enable that or you can configure Software Impersonation utilizing RBAC which suggests you can impersonate the proprietor of any mailbox you needed to entry. There isn’t any Impersonation within the REST API however in Azure you should utilize what they time period the Daemon or Server Software state of affairs or App-Solely tokens that are documented  https://docs.microsoft.com/en-gb/azure/active-directory/develop/active-directory-authentication-scenarios#daemon-or-server-application-to-web-api and https://msdn.microsoft.com/en-us/workplace/workplace365/howto/building-service-apps-in-office-365 . Within the present interplay of the module I do not cowl this Authentication state of affairs however will in future posts and interactions.

What you get out of the app registration course of is a ClientId to make use of in your script.

Right down to coding

For the Authentication code in my module I’ve used the beautiful cool  Present-AuthWindow perform from https://foxdeploy.com/2015/11/02/using-powershell-and-oauth/ and https://blogs.technet.microsoft.com/ronba/2016/05/09/using-powershell-and-the-office-365-rest-api-with-oauth/ which does the job of presenting the Azure logon field, any usertenant consents which can be mandatory and return again an Auth code that may then be used to get an Entry Token. With my implementation I’ve put all of the configurable variables right into a separate perform to name eg

perform Get-AppSettings(){
param( 

        )  
Start
     choose ResourceURL,ClientId,redirectUrl
$configObj.ResourceURL = "outlook.office.com"
$configObj.ClientId = "5471030d-f311-4c5d-91ef-74ca885463a7"
$configObj.redirectUrl = "urn:ietf:wg:oauth:2.0:oob"
return $configObj            

}

This makes the ClientId, ResourceURL and redirect straightforward to configure

The remainder of the code is fairly straight ahead organising and utilizing the HTTPClient object to make the required REST GET’s and POSTs. I’ve included a variety of capabilities that use the MailboxSetting https://msdn.microsoft.com/workplace/workplace365/APi/mail-rest-operations#GetAllMailboxSettings you may break these down into Getting the Oof (or Automated Replies), timezone and so forth. As a result of these are simply easy http GET’s the code to get the knowledge and parse the JSON outcomes is fairly easy. I’ve included a pattern Get-ArchiveFolder perform that demonstrates stacking requests to Get the new Archive Folder https://help.workplace.com/en-us/article/Archive-in-Outlook-2016-for-Home windows-25f75777-3cdc-4c77-9783-5929c7b47028?ui=en-US&rs=en-US&advert=US which was launched just lately. To get the Id of an Archive Folder in a Mailbox you make a request to https://outlook.workplace.com/api/v2.0/Customers(‘$MailboxName’)/MailboxSettings/ArchiveFolder and you then use the outcome returned to get the Folder in query which is perhaps helpful should you monitoring utilization stats or need to copy an merchandise into the archive.  I’ve put a replica of the module right here (which is a piece in progress) https://github.com/gscales/Powershell-Scripts/blob/grasp/RestHttpClientMod.ps1