Notes from the field: Using OAuth for ActiveSync and POP/IMAP in Exchange Online

[Guest The_Exchange_Team]

Hopefully, you have read some of our announcements around disabling Basic authentication in Exchange Online. We are getting close to the end of a more than three-year long journey.

 

Microsoft is going to disable Basic authentication for most Exchange Online protocols starting October 1, 2022. Seeing that we are past mid-August, you should have ample motivation to plan for the elimination of Basic authentication.

 

Recently, I have heard of two different types of questions related to implementation of OAuth – questions related to Exchange ActiveSync (EAS) use and POP/IMAP OAuth configuration.

 

Finding Basic auth ActiveSync usage in sign-in logs

 

Let’s start with EAS, which was widely used with Basic authentication in the past. Major mobile phone vendors and app developers now include OAuth support in their native email clients. As mentioned here, you can use the Azure AD sign-in logs to find users/clients who are still using Basic authentication with the "Client app" filter. In this case, look for the “Client app” value "Exchange ActiveSync" underneath “Legacy Authentication Clients”.

 

 

 

The report might give you a long list of users using Basic, but one corner case scenario comes when clients are using certificates to authenticate. In this case, the report might have “tricked” you and we just want to clarify that a bit here. Exchange Online has supported certificate-based authentication for EAS for a long time and this capability has been widely adopted. However, this report will also include certificate-based authentication under the Legacy Authentication Clients filter.

 

Even though certificate-based authentication is considered strong authentication, Azure AD consider it ‘Legacy’ as it’s not using OAuth. You can confirm the records are for certificate usage by opening the Authentication Details tab.

 

 

The Azure AD Sign-in report doesn´t allow you to filter out EAS using certificate-based authentication. So, let´s switch to the Azure AD Workbooks section, which allows you to query using Log Analytics (Workbooks are available for Azure Active Directory tenants with P1 or P2 licenses as described here.)

 

The Workbook named "Sign-Ins using Legacy Auth..." gives you a quick summary of the different protocols that are still using Basic authentication. But you also have the option to view the KQL query that’s used here by clicking the small button, "Open the last query in the Logs view."

 

 

Followed by:

 

 

This selection allows you to write your own queries by simply opening a new query beside the given one. We filtered out the certificate-based authentication clients with the following query:

 

 

SigninLogs

| project TimeGenerated,AuthenticationDetails,UserPrincipalName,ClientAppUsed

| where TimeGenerated > ago(2d)

| where ClientAppUsed == "Exchange ActiveSync"

| mv-expand authValue=todynamic(AuthenticationDetails)

| where authValue.authenticationMethod != "Certificate"

| project-away AuthenticationDetails

| summarize count() by UserPrincipalName

 

This sample query should give you a good starting point to remove Basic authentication dependencies for EAS.

 

POP and IMAP OAuth delegated access (interactive logon)

 

Let´s talk about POP and IMAP access. Although SMTP AUTH is closely related, Microsoft is not disabling Basic authentication for SMTP AUTH on October 1st , so we’ll focus only on POP and IMAP. We have heard from our customers that there is some confusion about this.

 

We have documented the requirements and configuration steps to use OAuth with POP/IMAP in Microsoft 365 in this article: Authenticate an IMAP, POP or SMTP connection using OAuth. You’ll see details about the registration of the required Azure AD applications and the permissions required for the access token to give Exchange Online the authorization of the mailbox access request.

 

As time is ticking, I'm getting more requests from admins that they need to enable OAuth support for different POP/IMAP applications that are using in their environment, which they can configure by creating an Azure AD application as described in the aforementioned article.

 

Their primary question is how to test their implementation before sharing further information with their business. While testing it with Basic authentication and using OpenSSL Clients (check sources from here: Binaries - OpenSSLWiki) was easy and straight forward, authenticating with the needed SASL XOAuth2 string is more cumbersome.

 

To help, I created a PowerShell script “Get-IMAPAccessToken.ps1” accessible here. The script uses the MSAL.PS library to provide a managed interactive OAuth authentication flow. The script also includes a token cache in Windows PowerShell to safely store the access token and refresh token after successful authentication. It´s important to use scope "Sign in to Outlook" for POP/IMAP access. You need to install the MSAL.PS PowerShell module as a prerequisite for the script (as of now, the latest version is PowerShell Gallery | MSAL.PS 4.37.0.0).

 

Using the received access token and the referenced documentation to generate the SASL XOAUTH2 login string:

 

 

…the script builds the needed XOAuth2 login string:

 

 

The script then opens a TLS 1.2 connection to the IMAP service in Exchange Online and tries to authenticate using the SASL XOAUTH2 encoded string. If this action is successful, it executes a simple IMAP folder listing and logs off again. This also allows you to see authentication and access using IMAP with OAuth based login on the newly registered Azure AD application. If everything works, you’ll get a folder listing using IMAP after OAuth authentication that looks like this.

 

 

You might have noticed that the script also gives you a possibility to pass the email address of a shared mailbox. This optional parameter allows you to check OAuth access to shared mailboxes, a use case I see very often with enterprise customers.

 

The popular IMAP app Thunderbird provides integrated OAuth support for Exchange Online mailbox access. In this case, admins don´t need to register their own apps. Instead, the Mozilla foundation pre-created a multi-tenant Azure application with a unique ClientID/ApplicationID. This capability is incorporated into the Thunderbird client and can be found here.

 

The easiest way to add Thunderbird to the allowed applications and grant consent to the organization, is by constructing an admin consent URL. To construct the consent URL, take the following URL:

 

Sign in to your account<TenantID>/oauth2/authorize?client_id 08162f7c-0fd2-4200-a84a-f25a4db0b584&response_type=code&prompt=admin_consent

 

Replace <TenantID> with your Tenant ID. This piece of information can be found under the Azure Active Directory blade in the Azure portal.

 

Please note currently Microsoft does not have plans to enable POP/IMAP Modern authentication support for Outlook on the desktop. If you are using Outlook on the desktop, please use a more modern protocol.

 

POP and IMAP OAuth application access

 

If you have not seen this, we announced the availability of the client credential flow which can be used with application permission for e.g. daemon scenarios Announcing OAuth 2.0 Client Credentials Flow support for POP and IMAP protocols in Exchange Online - Microsoft Tech Community

 

The needed Exchange cmdlet changes have been rolled out now, therefore I worked through the updated documentation here and created a new Azure AD application with the new available permissions.

 

 

Furthermore, as described in the documentation the service principal which has been created during Azure AD Application creation needs to be created/mirrored to Exchange Online. Where the new Cmdlet “New-ServicePrincipal” comes into play.

 

We need details from the registered Azure AD App, so I am using the Get-AzureADServicePrincipal cmdlet out of the AzureAD Powershell Module, which will return us all needed information to use the new Exchange Online cmdlet with the right values.

 

$ServicePrincipalDetails = Get-AzureADServicePrincipal -SearchString YourAppName

New-ServicePrincipal -AppId $ServicePrincipalDetails.AppId -ServiceId

$ServicePrincipalDetails.ObjectId -DisplayName "EXO Serviceprincipal for AzureAD App $($ServicePrincipalDetails.Displayname)"

 

From now on, this new ServicePrincipal can be used within Exchange Online to grant permission to access mailboxes. Using the Identity/ServiceID of the newly created ServicePrincipal.

 

 

Finally, I extended my referenced script to support the Client Credential flow using a client secret or certificate authentication. If you would like to use a certificate to authenticate as your registered app, take a look at steps described here. In the case of application permission usage, you would need to use script parameter “-targeMailbox” which is needed for the use case of application permission, as there is no associated mailbox to the service principal.

 

Summary

 

That's it! We hope that this article provides you with enough information to use more extended queries for your legacy authentication clients using the EAS example, and how to adopt OAuth for POP/IMAP more easily. Please use the comment section to ask questions or provide suggestions!

 

Special thanks to Greg Taylor, Mike Brown and Nino Bilic for all the help along the way.

 

Danijel Klaric

 

Continue reading...