Email Server with XOAUTH2

Email Server OAuth2 Configuration

OAuth2 (XOAUTH2) email authentication is based on the Client Credentials Flow, which involves an application exchanging its credentials, like Client ID, Client Secret, for an access token. This flow is used in Machine-to-Machine (M2M) communication.

In WebAdmin, a new entry with OAuth2 as the authentication type must be configured under email server settings.

The fields SMTP Server, Port, User, Client ID, Client Secret or Certificate Thumbprint, Token Endpoint, and Scope are required.

Note: If a certificate is used, it must be installed in the Current User profile that will be used by the application.

Microsoft Office 365 Exchange Online Configuration

First thing you’ll need to do is register you application with Microsoft’s Identity Platform. To do this, you can go to Microsoft’s QuickStart guide and follow instructions.

Then for configuring the API Permission for your application, follow the instructions for adding the SMTP permissions to your Entra AD application.

There is a summary of the necessary steps:

Go to https://entra.microsoft.com and register a new application.

After registering an application, now you have the required Client ID and Token Endpoint strings for SMTP configuration. They are available in the Overview of the registered application.

Next, add API permissions. In the list of APIs for your organization, search for “Office 365 Exchange Online”.

Chose “Application permissions”, search for, and select the “SMTP.SendAsApp” option.

Admin consent must then be granted

To obtain credentials, navigate to the Certificates & Secrets menu and create one. Either a Client Secret or Certificate can be used. If a certificate is defined in WebAdmin’s Email Server settings, it will be used instead of the Client Secret for greater security.

For the following commands, you first need to obtain the Object ID and Application ID of the application.

Register a new service in AD and grant email permissions to the application. In Azure PowerShell, execute the following commands:

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

Then register the Service Principal for the application

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

To grant permissions for your application to access an Office365 and/or Exchange account, you'll need to first get the Service Principal ID registered in the previous step using the following command:

Get-ServicePrincipal | fl

The “ExchangeObjectId” field is our Service Principal ID for registered service.

Once you have the Service Principal ID for your web service, use the following command to add full mailbox permissions for the email account that your web service will be accessing:

Add-MailboxPermission -Identity "noreply@example.com" -User <SERVICE_PRINCIPAL_ID> -AccessRights FullAccess

Your Microsoft Entra application can now access the allowed mailboxes via SMTP protocol using the OAuth 2.0 client credentials flow.

You must use https://outlook.office365.com/.default in the Scope field.

The SMTP server name, port and authentication method you can find in POP, IMAP and SMTP settings for Outlook.com