Setting up OAuth 2.0 compliant email listener in Integration Server using Microsoft Azure Active Directory (Azure AD)

Concepts

Typically, applications access Microsoft Exchange Server with basic authentication, which relies on sending usernames and passwords that are often saved on the device, increasing the risk of attackers capturing users’ credentials.

Due to such security risks, Microsoft has announced the end of support for basic authentication-based access to Exchange Servers. Instead of basic authentication, Microsoft encourages customers to use OAuth 2.0-based authentication in all applications that access Exchange Servers. For more information about Microsoft’s announcement, see Exchange Online deprecating Basic Authentication - Microsoft Lifecycle | Microsoft Docs

The benefits of implementing OAuth-based authentication for your application are:

• Applications can delegate the authorization of users to an OAuth server.
• Since access to resources in OAuth is based on an access token, it can be issued and revoked as required.
• Limit an application’s access to resources through an access token.

In an OAuth framework, there are three active roles. A client application, an authorization server, and a resource server. The authorization server is responsible for validating the user’s identity, granting and revoking access to resources, and issuing access tokens to the client application based on the supported grant type and in turn, the client application must send the access token to the authorization server in its requests for resources.

To use Integration Server to access or send emails through Microsoft Exchange Server, you must register the Integration Server instance as an OAuth client on Microsoft’s Azure portal for OAuth 2.0 compliance.

Since Integration Server uses the Authorization Code grant type, the Exchange Server expects an authorization code in the request for an access token.

Registering Integration Server on Microsoft’s Azure portal provides the OAuth credentials (Client ID, Tenant ID, and Client Secret) that Integration Server requires to request an authorization code from the Azure AD. Integration Server can then use the authorization code to acquire an access token from the Azure AD. Azure AD uses the access token to authenticate Integration Server requests and grant them access to the required resources on the Exchange Server.

In this setup, Integration Server is the client application while Azure AD is the authorization server and Microsoft Exchange Server is the resource server.

Description

In this article, you will learn to register Integration Server as an OAuth client in Azure AD.
As part of the registration process, you will:

• Obtain the Application (client) ID, Directory (tenant) ID, and create a Client Secret. All these credentials are required to obtain access and refresh tokens from Azure AD.
• Configure API permissions for Integration Server to access a mailbox on a Microsoft Exchange Server using the Microsoft Graph API.

After registering Integration Server as an application on Azure AD portal, you can:

• Create an OAuth 2.0 compliant e-mail port in Integration Server to access a mailbox on a Microsoft Exchange Server.
• Configure Integration Server to send emails through a Microsoft Exchange Server using OAuth 2.0 compliant SMTP outbound requests.

Actors

• Microsoft Azure Active Directory (Azure AD) portal allows you to register Integration Server as an OAuth client and behaves as the authorization server.
• Microsoft Exchange Server works as the Resource (Mail) server.
• Integration Server is the OAuth client.

Pre-conditions

• An Azure account with an active subscription.
• An Azure AD tenant that has the Global Administrator role.

For more information, see Quickstart: Register an application with the Microsoft identity platform

Important: The OAuth authentication type is supported only for e-mail listeners associated
with an IMAP server. By default, this authentication type is available in Integration Server, version 10.7. To use this authentication type in version 10.3, install 10.3 Core Fix 14 and in 10.5, install 10.5 Core Fix 7.

Basic Flow

1. Log in to the Azure Portal.

2. Click > Azure Active Directory > App registrations , and then New registration .
   

   

   App_New_Registration1014×735 133 KB

3. On the ‘ Register an application’ page, enter the necessary information and click Register . For more information, see Register an application. On successful registration, the Application (client) ID and Directory (tenant) ID are generated.

   Note: The Redirect URI that you enter during registration is the URL that Azure AD must use to send authentication responses to Integration Server.

   Enter the redirect URL in the following format:
   https://{ISHostName}:{port}/WmRoot/security-oauth-get-authcode.dsp

   

   App_Register831×620 115 KB

4. You can use the Microsoft Graph API to access a mailbox on an Exchange Server. To assign access privileges to Integration Server, configure API permissions as follows:

   1. Click View API Permissions to view the available API permissions. You might see the User.Read permission assigned by default. You can either retain or remove the permission and continue to configure the required permissions as follows:
      1. Click Add a permission > Microsoft Graph API > Delegated permissions.
      2. In the Select Permissions field, enter the first few letters of one of the following permissions, and select the permission once it appears in the list. Similarly, select the other permissions.
         • IMAP.AccessAsUser.All
         • offline_access
         • SMTP.Send
      3. Click Add Permissions.
      4. Click Grant admin consent.
      

      View_API_Permissions1523×803 82.4 KB
      

      App_Add_Permissions1920×796 74.7 KB
      

      App_Grant_Admin_Consent1291×390 25.5 KB

5. Configure a client secret, a unique string that Integration Server uses to request an access token. Perform the following steps:

   1. Go to Certificates and secrets > Client secrets, and then click New client secret.
   2. In the Description field, enter a name to identify the client secret.
   3. Select when the client secret expires and then click Add.

   Important: Note the client secret before you leave the page.

   What next?

   With the following details, set up an OAuth 2.0 compliant e-mail port using Integration Server Administrator. Once the port is created, Integration Server programmatically acquires the authorization code, followed by access and refresh tokens from the Azure AD.

   • Auth URL : https://login.microsoftonline.com/<TenantID>/oauth2/authorize

   • Client ID : The application (Client) ID obtained on completing step 3.

   • Client Secret : The string that you generated on completing step 5.

   • Scope : offline_access https://outlook.office365.com/IMAP.AccessAsUser.All https://outlook.office365.com/SMTP.Send

   • Access Token URL : https://login.microsoftonline.com/<TenantID>/oauth2/token

   • Redirect URL : The value that you entered for Redirect URI in step 3.

   The following image shows a sample email client configuration with OAuth credentials.

   

   image731×788 89.3 KB

   On saving the changes, the following screen will appear:

   

   IS_Email_Port_OAuth_Config_Saved991×756 51.2 KB

   Using OAuth 2.0 authentication in the built-in SMTP services

   To send outbound SMTP requests from Integration Server built-in services using the OAuth mechanism, perform the following steps:

   1. Obtain the authorization code manually by sending a request through a browser in the following format:

      https://login.microsoftonline.com/<TenantID>/oauth2/authorize?response_type=code&prompt=login&redirect_uri=http://host:{port}/WmRoot/security-oauth-get-authcode.dsp&client_id= <clientID>&scope=<scope>

      Here, response_type is set to code to inform the OAuth server that Integration Server expects an authorization code as the response at the mentioned redirect_uri.

      The response from the OAuth server would look like this:

      http://host:{port}/WmRoot/security-oauth-get-authcode.dsp?code=AQABAAIAAAAm-xxxx&session_state=yyyy

      Here, the value of code is the authorization code.

   2. Run the pub.client.oauth:getExternalAccessToken service with the grant_type as authorization_code and code as the authorization code received in the previous step, along with other input parameters as shown in the following image:
      

      

      BIS_getExternalAccessToken767×265 5.61 KB

   3. Run the pub.client:smtp service using the output of the previous step as shown in the following image:
      

      

      BIS_Oauth_SMTP_Service805×393 8.45 KB

   Further read:
   Learn how to connect webMethods Integration Server to Azure Service Bus: Connecting Integration Server to Azure Service Bus