Friday, August 24, 2018

Using Guest Access in PowerShell to access Unified Groups and Teams in Office365

This is a continuation somewhat of my previous post on using a generic oAuth script to access EWS but in this post I'm going to look at how you can authenticate as a Guest user to a tenant you have been granted Guest access to and then access the resources like a Unified Office365 Group or Teams( because Teams uses Groups) via the Graph API.

To Access another tenant as a Guest (considering that Guest Access is enabled and you have accepted the invitation and logged in at least once with that user) you need to generate an Access Token against the Target tenants endpoints. To do this you can discover what a particular tenants Authentication and Token endpoints are by making a request like the following

$RequestURL = "https://login.windows.net/{0}/.well-known/openid-configuration" -f $TargetDomain
$Response = Invoke-WebRequest -Uri  $RequestURL
$JsonResponse = ConvertFrom-Json  $Response.Content

This will return a result like the following


Out of this result the Authorization Endpoint and the Token_endpoint are what you need to make a successful authentication against the Target Tenant to get a guest access token.

For technical completeness the above step is not necessarily needed as the endpoint should also support you using the domain name as per https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-protocols-oauth-code . But like many things in IT there are many ways of doing the same things.

I've posted up a script that first does the above the request and then will authenticate against the Target Tenant and return an Access Token that can then be used to access the Graph. I've created a test cmdlet called Test-GuestAuth that will enumerate the unified Groups the guest is a member of and get the first two conversation items  in each of the unified Groups, I've put the code up for this here

The script is on GitHub here https://github.com/gscales/Powershell-Scripts/blob/master/GenericOauthGuest.ps1

To use this script use something like the following

Test-GuestAuth -UserName gscales@datarumble.com -TargetDomain guesttenant.contos.com

For the clientId you would need to use in oAuth that clientId has to have been consented to by the Target Tenant admins, in the above script I've used the default Office clientId which should be enough to get access to Group conversation etc.

Friday, August 10, 2018

Dependency free Generic EWS oAuth PowerShell example for Office365

Microsoft recently posted an update that will affect those people who use EWS in applications and script against Office365 https://blogs.technet.microsoft.com/exchange/2018/07/03/upcoming-changes-to-exchange-web-services-ews-api-for-office-365 

While 2020 is a few years away what this means is that if you are using Basic Authentication in your EWS scripts or applications that on the 13th October 2020 your app will stop working. Given the amount of time you have and the changes required to support oAuth nobody should really be caught out by this but procrastination and people not understanding legacy applications will mean I'm sure this date won't pass without any infamy.

Within PowerShell scripts you have two options to generate the oAuth tokens you need to keep you script working. One is to use a dependency library like ADAL to do it which Ingo posted a really good write up for https://ingogegenwarth.wordpress.com/2018/08/02/ews-and-oauth the other is just create some of your own script code to do the Authentication and managed of the Tokens. As part of my Exch-Rest library because I wanted to make this dependency free I wrote my own routines for Getting and Renewing OAuth tokens needed which can also be used for EWS . So in this post I've separated those out and included them into a simple header script that can be used to do oAuth against Office365.

EWS Managed API and oAuth

If you using the EWS Managed API in your scripts which the majority of people do it contains code already to add the correct Bearer headers in for Oauth if you use  the OAuthCredentials class


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

If your using the ADAL library be aware while its correct to say it does have a TokenCache and code to refresh the tokens once they expire this won't work with the EWS Managed API. As you can see from the code above because you only pass in the Access_Token (as a String) into this class it doesn't do any active management of the Token from that point. This means if you just pass in the AccessToken from whatever method you used to generated it if your script runs for more then one hour your code will fail at the 60 minute point. Unfortunately the EWS Managed API doesn't have a CallBack to use where you could link in the ADAL libraries refresh function (or your own code to manage the token refresh) to check before making a request. So one important modification you should make to your code if before it makes an EWS call (eg Bind,Load,findItems etc) you will need to add in code to check for expired tokens. The ADAL has the acquiretokensilentasync method for this (this will return the token from cache or renew if necessary), in the code in my example I have the Invoke-ValidateToken function which does the renewal after 50 minutes to avoid token expiration.

Application registrations

Its always a good idea to create your own application registration as this gives you the ultimate control over what rights a script or application will have in your environment (although EWS really only has one grant that will work which is full Mailbox Access). But creating you own ApplicationId's allows you  track the use of the ApplicationId and potential audit the miss use of a particular application more effectively. For scripts using the Native application type and the Out of Band redirect(urn:ietf:wg:oauth:2.0:oob) is generally a good idea as you won't have an registered endpoint online to redirect the Authentication to once its complete. There are some good walk throughs to do this https://blogs.technet.microsoft.com/dawiese/2017/04/15/get-office365-usage-reports-from-the-microsoft-graph-using-windows-powershell/ shows the newer portal screens.

Last word on security

While oAuth is a great improvement in security over basic Authentication its not the panacea in itself for the InfoSec issues the IT industry faces as a whole. So you should see implementing oAuth as a step in the right direction but be careful and always treat access tokens like you would usernames and passwords (eg don't store them in plain text) and look at always strengthening your authentication with measures like Multi-Factor Authentication. 


The script includes a Test function which just binds to the Inbox so you use it like

Import-Module .\GenericOauthEWS.ps1 -Force

Test-EWSConnection -MailboxName gscales@datarumble.com

Testing

Like any script you get off the Internet you should always do your own testing but consider these points of failure for Oauth tokens that you wouldn't have to have previously considered with Basic Auth

  • If things run for more the 1 hour does my token renew correctly
  • If the AccessToken suddenly becomes Invalid for X Reason and I get a 401 error in my code will it handle the reauth (using the RefreshToken). (for the second part you need to build in an exception handler in you code for 401 error when using oAuth)
Regional Azure Endpoints

This script is hardcoded to use the common (Production) Azure Authentication endpoint that the majority of Office365 Tenants would use however some regions like China,Germany and US Government have their own dedicated endpoint so you would need to change the URL in this case see https://docs.microsoft.com/en-us/sharepoint/dev/solution-guidance/extending-sharepoint-online-for-germany-china-usgovernment-environments . There are ways of discovering the Endpoint dynamically which I'll included in future updates of the script.