Dependency free Generic EWS oAuth PowerShell instance for Workplace365

Dependency free Generic EWS oAuth PowerShell instance for Workplace365 Microsoft not too long ago posted an replace that may have an effect on these individuals who use EWS in functions and script towards Workplace365 

Whereas 2020 is a couple of years away what this implies is that if you’re utilizing Primary Authentication in your EWS scripts or functions that on the 13th October 2020 your app will cease working. Given the period of time you might have and the modifications required to assist oAuth no one ought to actually be caught out by this however procrastination and folks not understanding legacy functions will imply I am positive this date will not go with none infamy.

Inside PowerShell scripts you might have two choices to generate the oAuth tokens it’s essential hold you script working. One is to make use of a dependency library like ADAL to do it which Ingo posted a extremely good write up for the opposite is simply create a few of your personal script code to do the Authentication and managed of the Tokens. As a part of my Exch-Relaxation library as a result of I wished to make this dependency free I wrote my very own routines for Getting and Renewing OAuth tokens wanted which can be used for EWS . So on this submit I’ve separated these out and included them right into a easy header script that can be utilized to do oAuth towards Workplace365.

EWS Managed API and oAuth

For those who utilizing the EWS Managed API in your scripts which the vast majority of individuals do it incorporates code already so as to add the right Bearer headers in for Oauth in case you use  the OAuthCredentials class

        $OAuthCredentials = New-Object Microsoft.Trade.WebServices.Knowledge.OAuthCredentials((ConvertFrom-SecureStringCustom SecureToken $Script:Token.access_token))
        $service.Credentials = $OAuthCredentials

In case your utilizing the ADAL library remember whereas its right to say it does have a TokenCache and code to refresh the tokens as soon as they expire this may not work with the EWS Managed API. As you possibly can see from the code above since you solely go within the Access_Token (as a String) into this class it does not do any energetic administration of the Token from that time. This implies in case you simply go within the AccessToken from no matter methodology you used to generated it in case your script runs for extra then one hour your code will fail on the 60 minute level. Sadly the EWS Managed API does not have a CallBack to make use of the place you may hyperlink within the ADAL libraries refresh perform (or your personal code to handle the token refresh) to examine earlier than making a request. So one necessary modification it’s best to make to your code if earlier than it makes an EWS name (eg Bind,Load,findItems and so forth) you’ll need so as to add in code to examine for expired tokens. The ADAL has the acquiretokensilentasync methodology for this (this can return the token from cache or renew if mandatory), within the code in my instance I’ve the Invoke-ValidateToken perform which does the renewal after 50 minutes to keep away from token expiration.

Software registrations
Its all the time a good suggestion to create your personal utility registration as this provides you the final word management over what rights a script or utility could have in your setting (though EWS actually solely has one grant that may work which is full Mailbox Entry). However creating you personal ApplicationId’s permits you  observe using the ApplicationId and potential audit the miss use of a specific utility extra successfully. For scripts utilizing the Native utility sort and the Out of Band redirect(urn:ietf:wg:oauth:2.0:oob) is usually a good suggestion as you will not have an registered endpoint on-line to redirect the Authentication to as soon as its full. There are some good stroll throughs to do that exhibits the newer portal screens.

Final phrase on safety

Whereas oAuth is a superb enchancment in safety over primary Authentication its not the panacea in itself for the InfoSec points the IT business faces as a complete. So it’s best to see implementing oAuth as a step in the proper route however watch out and all the time deal with entry tokens such as you would usernames and passwords (eg do not retailer them in plain textual content) and take a look at all the time strengthening your authentication with measures like Multi-Issue Authentication. 

The script features a Take a look at perform which simply binds to the Inbox so you utilize it like
Import-Module .GenericOauthEWS.ps1 -Pressure
Take a look at-EWSConnection -MailboxName


Like every script you get off the Web it’s best to all the time do your personal testing however think about these factors of failure for Oauth tokens that you just would not should have beforehand thought-about with Primary Auth
  • If issues run for extra the 1 hour does my token renew accurately
  • If the AccessToken all of the sudden turns into Invalid for X Purpose and I get a 401 error in my code will it deal with the reauth (utilizing the RefreshToken). (for the second half it’s essential construct in an exception handler in you code for 401 error when utilizing oAuth)
Regional Azure Endpoints
This script is hardcoded to make use of the widespread (Manufacturing) Azure Authentication endpoint that almost all of Workplace365 Tenants would use nonetheless some areas like China,Germany and US Authorities have their very own devoted endpoint so that you would wish to vary the URL on this case see . There are methods of discovering the Endpoint dynamically which I will included in future updates of the script.

Leave a Reply