Microsoft 365 and Workflow POP3 Email Listener with OAuth 2.0

In October 2022, Microsoft began disabling Basic authentication in Microsoft 365 for IMAP, POP3 and EWS. As a consequence, the classic username/password authentication no longer works with Exchange Online, and the MRI Evolution Workflow application has been updated to allow use of OAuth 2.0 authentication for the POP3 email listener node.

In order for the MRI Evolution Workflow application to access Microsoft 365 mailboxes using OAuth 2.0 authentication, it must be registered with Microsoft, assigned the relevant permissions, configured for mailbox access and then MRI Evolution Workflow Settings configured accordingly.

The following describes the end-to-end steps required to enable POP3 access for the MRI Evolution Workflow, POP3 email listener node, outside of the MRI Evolution web based system.

    Register Workflow application in your Azure Portal

  1. Log into the Azure Portal. If you don't have an account there yet, create it. You also have to set up a tenant that represents your company.

  2. If you administer more than one tenant, use Directories + subscriptions filter to select the tenant for whom to register an application.

    3. Register MRI Evolution Workflow

  3. In the Azure Portal ⇒ expand the left menu ⇒ select Azure Active Directory ⇒ select App registrations ⇒ click + New registration.

    Note: The Azure Portal is constantly evolving, so if you cannot find this page, use the search bar.

  4. Enter a Name for your POP3 email listener application, choose which kind of accounts are going to use it, and click Register.

  5. You have successfully registered your application and you can view its associated IDs. Some of these will be needed later, highlighted below, to obtain an OAuth 2.0 token. It is a good idea to copy these to Notepad, or similar, for use in later steps.

    6. Set up client secret (application password)

  6. In the left menu, select Certificates & secrets ⇒ click + New client secret.

  7. Enter a suitable description for the client secret, choose an appropriate expiration period, and click Add.

  8. Immediately copy and save to Notepad, or similar, for use in later steps, the newly created client secret's Value (not Secret ID). You will not be able to view the Value after this stage.

    9. Add app permissions

  9. In the left menu, select API permissions ⇒ click + Add a permission.

  10. Navigate to APIs my organization uses tab ⇒ type Office 365 Exchange in the search bar ⇒ click Office 365 Exchange Online entry.

  11. Click Application permissions ⇒ type AccessAsApp ⇒ POP.AccessAsApp ⇒ click Add permissions.

  12. The newly-added POP.AccessAsApp permission has to be approved by your organisation's administrator. Ask them to grant consent to your application by clicking Grant admin consent for [organisation].

  13. Application permissions have been granted. Optionally, you can remove the delegated User.Read permission which is not needed for MRI Evolution Workflow, POP3 email listener - click the context menu on the right side of the permission and select Remove permission.

    14. Add mailbox access permissions

  14. Now, you have to assign access permissions for your Microsoft 365 mailboxes. There is no web UI for this yet - you have to use PowerShell.

  15. Install the required PowerShell modules.

    16. Note: You can skip this step if you have already installed AzureAD and ExchangeOnlineManagement modules.

    Open your PowerShell as Administrator, and run:

    Install-Module -Name AzureAD

    Install-Module -Name ExchangeOnlineManagement

    Confirm installation from PSGallery by typing Y + Enter.

  16. Get the service principal ID associated with your application.

    17. Note: You will be asked to log into your Azure account.

    $AppId = "YOUR_APP_ID_HERE" - Use value saved in Step 5 above

    $TenantId = "YOUR_TENANT_ID_HERE" - Use value saved in Step 5 above

    Import-module AzureAD

    Connect-AzureAd -Tenant $TenantId

    ($Principal = Get-AzureADServicePrincipal -filter "AppId eq '$AppId'")

    $PrincipalId = $Principal.ObjectId

  17. Register the service principal for your application.

    18. Note: You will be asked to log into your Exchange Online account.

    $DisplayName = "Enter name for POP3 here"

    Import-module ExchangeOnlineManagement

    Connect-ExchangeOnline -Organization $TenantId

    New-ServicePrincipal -AppId $AppId -ServiceId $PrincipalId -DisplayName $DisplayName

  18. Add FullAccess mailbox permissions to the POP3 mailbox you want to access from the MRI Evolution Workflow, POP3 email listener.

    19. Add-MailboxPermission -User $PrincipalId -AccessRights FullAccess -Identity "mailbox.1@example.org"

  19. You have now registered MRI Evolution Workflow, POP3 email listener for accessing Microsoft 365 mailboxes via POP3 protocol and received its Application (client) ID, Client secret and Directory (tenant) ID.

    20. These strings are going to be used by the MRI Evolution Workflow, POP3 email listener to authenticate to Microsoft 365 via OAuth 2.0 and receive an OAuth token. This token is then used to authenticate to Exchange Online using the POP3 protocol.

    Configuring MRI Evolution Workflow POP3 Email Listener Settings

  20. Log in to the MRI Evolution Workflow Settings application.

    21. Note: MRI Evolution Workflow Settings is a separate Windows based application from the main MRI Evolution web based system. The following configuration steps cannot be carried out in the MRI Evolution system.

    Navigate to Modules ⇒ Settings ⇒ Email Accounts ⇒ General ⇒ Click the Add button.

  21. Enter relevant values, as per below, to configure the POP3 email listener:
    22. Field Name Details
    POP3 Accounts Select "New POP3 Account" from the dropdown.
    Name Enter a suitable name.
    Authentication Type Select "Microsoft 365" from the dropdown.
    Host You must use the Microsoft default server details - "outlook.office365.com".
    Port You must use the Microsoft default value of "995".
    Username Enter the SmtpAddress of the mailbox that will be listened to by the POP3 email listener.
    Client Id Use value saved in Step 5 above
    Client Secret Use value saved in Step 8 above
    Tenant Id Use value saved in Step 5 above
    Scope You must use Microsoft's default of "https://outlook.office365.com/.default".

    Note: Microsoft's default values above my change over time.

  22. Click the Test button to verify the connection, if successful, the email messages currently in the POP3 mailbox will be listed in the bottom panel. It is a good idea to send one or more test emails to the mailbox beforehand, in order to prove the email listener is working.

    23. Validation messages will be displayed to the user if the Test is unsuccessful. Correct the details accordingly and try again.

  23. Click the Apply button to save the details. The POP3 connection will now be available to select in MRI Evolution Workflow nodes related to emails.