Microsoft Exchange IMAP configuration with OAuth 2.0

Owned by Tamas Kalman
Last updated: Feb 27, 2024 by Zszugyi
4 min read

Effective October 1, 2022, Microsoft began disabling Basic authentication for Outlook, EWS, RPS, POP, IMAP, and EAS protocols in Exchange Online. This means that for TeleMessage import sources using Exchange will no longer work with simple username and password authentication, instead OAuth 2.0 authentication must be used.

Azure Active Directory is now Microsoft Entra ID.

Register application in Azure

For Import Service on a Media Repository server to use OAuth 2.0, an application needs to be registered in Azure.

Step 1 - Go to https://portal.azure.com

Step 2 - Select the directory (tenant) where the Exchange service is running. Click on Switch directory in the upper-right corner drop-down menu. Then select the appropriate directory from the list.


Step 3 - Go to Azure Active Directory. If it's not on the opening page, use the search or find it under All services.

Step 4 - Select App registrations on the left, and click on New registration.



Step 5 - Enter a name of your choice, then click Register.




Step 6 - Create a new secret for the application.




Step 7 - Copy and save the secret's value. It is only shown for a short period after created. It cannot be viewed later. 

Step 8 - The two other values we need from the application is the application (client) id and the directory (tenant) id. Both can be copied from Overview:

Configure TeleMessage import source

On the Import source configuration page, select OAuth 2.0 for Authentication Mode, and set Application (Client) ID, Application (Client) Secret, Directory (Tenant) ID to their respective values from the registered Azure application above.



Register service principals in Exchange

This whole section is quoted from here: Authenticate an IMAP, POP or SMTP connection using OAuth


Once your Azure AD application is consented to by a tenant admin, the tenant admin must register your AAD application's service principal in Exchange via Exchange Online PowerShell. This is enabled by the New-ServicePrincipal cmdlet.

To use the New-ServicePrincipal cmdlet, install the ExchangeOnlineManagement and connect to your tenant as shown in the following snippet.


Install-Module -Name ExchangeOnlineManagement -allowprerelease
Import-module ExchangeOnlineManagement 
Connect-ExchangeOnline -Organization <tenantId>


If you still get an error running the New-ServicePrincipal Cmdlet after you perform these steps, it is likely due to the fact that the user doesn't have enough permissions in Exchange online to perform the operation.

The following is an example of registering an Azure AD application's service principal in Exchange:


New-ServicePrincipal -AppId <APPLICATION_ID> -ServiceId <OBJECT_ID> [-Organization <ORGANIZATION_ID>]


The OBJECT_ID is the Object ID from the Overview page of the Enterprise Application node (Azure Portal) for the application registration. It is not the Object ID from the Overview of the App Registrations node. Using the incorrect Object ID will cause an authentication failure.

The tenant admin can find the service principal identifiers referenced above in your AAD application's enterprise application instance on the tenant. You can find the list of the enterprise application instances on the tenant in the Enterprise applications blade in the Azure Active Directory view in Azure Portal.

You can get your registered service principal's identifier using the Get-ServicePrincipal cmdlet.


Get-ServicePrincipal | fl


The tenant admin can now add the specific mailboxes in the tenant that will be allowed to be access by your application. This is done with the Add-MailboxPermission cmdlet.

The following is an example of how to give your application's service principal access to one mailbox:


Add-MailboxPermission -Identity "john.smith@contoso.com" -User <SERVICE_PRINCIPAL_ID> -AccessRights FullAccess


VFC can now access the allowed mailboxes via the POP or IMAP protocols using the OAuth 2.0 client credentials grant flow. For more information, see the instructions in Permissions and consent in the Microsoft identity platform.


Troubleshooting

If the import fails, do the following checks:

  • Check if the client secret hasn't expired in Azure. Create a new one if needed and update on the import source configuration page.
  • The default scope for the OAuth2 token is 'https://outlook.office365.com/.default'. If this needs to be changed for some reason, the correct scope can be set/edited in the registry with the following entry:

HKEY_LOCAL_MACHINE\SOFTWARE\Verba\Archive Import\IMAP\Oauth2TokenScope