Using Modern Authentication (OAuth2) as Email Authentication Method with O365

The modern authentication described in this document is supported in ESM version 2021.1 and more recent versions.

To configure modern authentication (OAuth2) instead basic authentication for the SMTP and IMAP protocols in ESM, we need to do three steps:

1. ESM needs to be registered as an approved application in the Azure Active Directory through Microsoft Azure portal.
2. The registered application needs to be granted access for the O365 mailbox account used for Efecte.
3. ESM platform settings need to be updated to be in sync with the Microsoft Azure settings.

It is recommended to do steps 1-2 using the same O365 account the emails are read from to ESM. If not possible the application needs an Owner to be set up in the Azure AD.

Registering ESM as an Application in Microsoft Azure

Prerequisites

• A Microsoft Azure account with an active subscription (the O365 email account to be used with ESM).
• An Azure tenant available under which you will register your application.

Register an Application

Registering an application establishes the trust relationship between ESM and the Microsoft identity platform. The trust with registered application is unidirectional: application (ESM) trusts the Microsoft identity platform, and not the other way around. Trust is based on the id created in the registration process.

Follow these steps to create the app registration:

• Sign in to the Microsoft Entra portal (https://entra.microsoft.com) or Azure portal (https://portal.azure.com/).
• If you have access to multiple tenants, use the Directory + subscription filter   in the top menu to select the tenant in which you want to register an application.
• Search for and select Microsoft Entra ID (previously Azure Active Directory).
• Under Manage, select App registrations > New registration.
• Enter a Name for your application. Users of your app might see this name, and you can change it later.
• Specify who can use the application, sometimes referred to as the sign-in audience. For ESM, choose Accounts in this organizational directory only option.
• Don't enter anything for Redirect URI (optional).
• Select Register to complete the initial app registration.

When registration completes, the Azure portal displays the app registration's Overview pane, which includes its Application (client) ID. Also referred to as just client ID, this value uniquely identifies your application in the Microsoft identity platform.

Add permissions to access the O365 mailbox

In order to send and receive emails from O365 mailbox with OAuth, we need to define API permissions scopes for the ESM application we previously registered to the Azure Active Directory.

Delegated permission to Microsoft Graph

Configure delegated permission to Microsoft Graph to enable ESM to perform operations on behalf of the APP owners, for example reading or sending their emails.

• Sign in to the Microsoft Entra portal (https://entra.microsoft.com) or Azure portal (https://portal.azure.com/).
• If you have access to multiple tenants, use the Directory + subscription filter in the top menu to select the tenant containing your previously registered ESM application.
• Select Azure Active Directory > App registrations, and then select your client application (if not shown on the list, check that the page is showing All applications).
• Select API permissions > Add a permission > Microsoft Graph.
• Select Delegated permissions. Microsoft Graph exposes many permissions, with the most commonly used shown at the top of the list.
• Under Select permissions, select the following permissions:
  • IMAP.AccessAsUser.All - Read and write access to mailboxes via IMAP.
  • SMTP.Send - Send emails from mailboxes using SMTP AUTH.
  • openid - Sign users in.
  • User.Read- Sign in and read user profile.
  • offline_access - Maintain access to data you have given it access to.
• Select Add permissions to complete the process.

As an admin, you should also grant consent on behalf of all ESM Admin users, so they're not prompted to do so when they log into the mailbox. Admin consent is discussed in the next subchapter. If you define Admin consent beforehand, then the users who log into the mailboxes are not prompted to ask separately for Admin consent.

ESM admins should  log in weekly to the email accounts that are read into ESM to check if the spam folder contains actual customer emails and move them to the folder from which the emails are fetched to ESM (usually inbox folder). 
Also, admins should check for cases if emails are not fetched successfully into ESM. If there are large emails in the inbox that cannot be fetched into ESM, those should be moved into another folder to avoid errors.

Admin Consent Button

The Grant admin consent for {your tenant} button allows an admin to grant admin consent to the permissions configured for the application. When you select the button, a dialog is shown requesting that you confirm the consent action.

After granting consent, the permissions that required admin consent are shown as having consent granted:

The Grant admin consent button is disabled if you aren't an admin or if no permissions have been configured for the application. If you have permissions that have been granted but not yet configured, the admin consent button prompts you to handle these permissions. You can add them to configured permissions or remove them.

Authentication Settings

To enable ROPC authorization flow to work properly for the application and for ESM to Authenticate and get access tokens, we need to enable Default Client type setting (as shown in screenshot) in Authenticate → Advanced Settings.

By default, the setting is set to No (confidential client). Updating it to Yes converts the default client type to public client. This is a very important step , if not done then you will see below error:

-  AADSTS7000218: The request body must contain the following parameter: client_assertion or client_secret when authenticating to Azure AD. 

We have now completed the process of application registration and set up. After this we just have to add following platform settings in ESM to use above setup.

ESM Platform Settings

To set up ESM to use the OAuth2 endpoint we just created in the Azure portal for emails, please go to ESM admin view and navigate to Maintenance > System settings > Edit Platform Settings. Use the filter field to find the following mail settings one by one and set the following properties:

mail.store.oauth.enabled = true
mail.transport.oauth.enabled = true
mail.oauth.authorize.endpoint = https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/authorize
mail.oauth.client.id = {clientId}
mail.oauth.scopes = https://outlook.office365.com/IMAP.AccessAsUser.All,https://outlook.office365.com/SMTP.Send

The clientId and authorize endpoint can be found from the Azure Active Directory frontpage for the application we registered for ESM. Please check below on how to get them.

Please note that mailtasks use the settings configured in their properties. In case connection and authentication settings have been defined in in the mailtask properties (instead of defining them centrally in platform settings for all mailtasks), please set the settings listed above directly into the mailtask properties for each mailtask.

References

https://docs.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth 
https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app 
https://docs.microsoft.com/en-us/azure/active-directory/develop/msal-authentication-flows 
https://blogs.aaddevsup.xyz/2020/09/whats-the-security-implication-of-changing-the-default-client-type-from-confidential-to-public-in-azure-ad/