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

Utilizing the Workplace365/Alternate 2016 REST API to entry Mailbox knowledge utilizing PowerShell half 1 The Outlook REST API ‘s https://dev.outlook.com/ that are a part of Workplace365 and Alternate 2016 is among the methods new function are being delivered for Mailbox purchasers which beforehand the place delivered through EWS operations. They’re additionally a part of the Graph API https://graph.microsoft.io/en-us/docs which is Microsoft’s envisioned unified knowledge entry API that has the last word aim of permitting you to entry all of your knowledge endpoints through a single interface/endpoint.

On this sequence of posts I will be taking a look at writing a PowerShell module that makes use of the REST API to entry Mailbox knowledge and among the new Alternate options like Teams and the targeted Inbox. To maintain issues easy and versatile I am not going to make use of any helper libraries (just like the ADAL library or the Outlook Providers Shopper) which I hope will make the script as moveable and simple to make use of as potential with the one draw back of whereas making the code a little bit extra complicated I will use the System.Web.HttpClient courses for better flexibility as apposed the native PowerShell Relaxation interfaces.

Getting began

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

Leave a Reply Cancel reply