Setting up mailboxes for OAuth 2.0 authorization

Starting with version 8.5.107.06, E-mail Server supports the OAuth 2.0 authorization access to Microsoft Exchange Online API for Office 365 with the IMAP and EWS protocols.

To set up mailboxes using the OAuth 2.0 authorization access:

1. Create a Microsoft Azure application.
2. Configure Genesys E-mail Server.
3. Configure Proxy.

Creating a Microsoft Azure application

OAuth defines the following grant types: authorization code, implicit, resource owner password credentials, and client credentials. The Genesys solution uses resource owner password credentials.

1. Follow Steps 1-8 as described in this documentation to register an Azure public client application for the mailbox(es) that will be accessed by Genesys E-mail Server. Note that a single Azure application can support all mailboxes for the same company.
2. In step 6, for entering the name in Supported account types:
   • Select Accounts in any organizational directory (Any Azure AD directory – Multitenant).

     Note: Single-tenant accounts, Accounts in this organizational directory only, are also supported.

   • Leave the Redirect URI empty (as well as in Step 7).
3. Copy and paste the Application (client) ID and the Directory (tenant) ID into a text document for insertion during the E-mail Server configuration.

After the application is created, it should look similar to this (click to expand it):

Where esj_office365_imap is the Azure application name.

If you open the Supported account types and Redirect URIs, it should look similar to this:

The Application ID URI should be empty:

Adding Application Permissions

Read through the article Permissions and consent in the Microsoft identity platform endpoint to learn about permissions and consent.

You might want to consult this document, Configure permissions for Microsoft Graph, although it focuses on getting permissions for the Graph API.

For IMAP and EWS, the application must have the following permissions granted by the company's administrator, depending on the email protocols used:

(Click to expand)

Important

• For the EWS protocol, the Azure application must have the following permission:

  User.Read

  EWS.AccessAsUser.All

• For the IMAP protocol, the Azure application must have the following permission:

  User.Read

  IMAP.AccessAsUser.All

Setting up a mailbox

The mailbox has the following special settings in the company’s system:

• Multifactor authentication is disabled on the mailbox.
• The IMAP protocol is enabled (if IMAP is used).
• The POP3 protocol is enabled (if POP3 is used). (Note that E-mail Server does not support OAuth2 for POP3 yet.)
• Nothing is needed for the EWS protocol.

Configuring Genesys E-mail Server

To configure E-mail Server:

• Set the JavaMail property mail.<type>.auth.mechanisms (where <type> can be ews or imap) to XOAUTH2. (To disable OAuth 2.0, remove the JavaMail property.)
• Configure new options in the smtp-client section.
• Configure new options in the pop-client section.

Configuring the smtp-client section

Only an SMTP client with the EWS type can support OAuth 2.0.

Configure the following new configuration options:

• directory-id—Specify the Directory (tenant) ID of the registered Microsoft Azure application for the Office 365 mailbox in the SMTP client.
• tenant-authority—Specify the authority server of the registered Microsoft Azure application for the Office 365 mailbox in the SMTP client. For Office 365, the default configuration value is https://login.microsoftonline.com/.
• client-id—Specify the Client ID of the registered Microsoft Azure application for the Office 365 mailbox in the SMTP client.
• scope—Specify the access token scope. For Office 365, the default configuration value is https://outlook.office.com/.default.
• token-expiry-margin-time— Specify the amount of time an SMTP connection for the EWS type remains connected before its access token expires and the server closes the connection.

Configuring the pop-client section

Only a POP client with the EWS or IMAP type can support OAuth 2.0.

Configure the following new configuration options:

• directory-id—Specify the Directory (tenant) ID of the registered Microsoft Azure application for the Office 365 mailbox in the corresponding POP client.
• tenant-authority—Specify the authority server of the registered Microsoft Azure application for the Office 365 mailbox in the corresponding POP client. For Office 365, the default configuration value is https://login.microsoftonline.com/.
• client-id—Specify the Client ID of the registered Microsoft Azure application for the Office 365 mailbox in the corresponding POP client.
• scope—Specify the access token scope. For Office 365, the default configuration value is https://outlook.office.com/.default.

Configuring Proxy

E-mail Server implements Microsoft identity platform and OAuth 2.0 Resource Owner Password Credentials. It sends the client identification and user's credentials to the Microsoft Identity Platform (IDP) to request an access token. If a proxy has been used to access Office 365, you must have additional access to the Microsoft IDP (https://login.microsoftonline.com/, default https port is 443) and keep the same credentials if they were created previously.

To comply with RFC 6749, the Microsoft IDP validates the resource owner credentials by accessing the resource owner.

Known Limitations

Currently, E-mail Server does not support OAuth2 for POP3.