Enhancing B2B Mail Client Adapter to access Microsoft Exchange Online with OAuth 2.0

Follow this section to enhance B2B Mail Client Adapter to support IMAP with OAuth 2.0 for Microsoft Exchange Online only.

B2B Mail Client Adapter is implemented using JavaMail. Till now for authentication, you passed the user name and password in the properties of POP3 or IMAP protocols. However, with the OAuth 2.0 implementation, you need to make a request to the authorization point to get an access token. The access token is included in the request for connection to the mail provider.

Remember: The request to get access token must be as per OAuth 2.0 specification.

How the OAuth 2.0 Feature Works

When a work-flow runs to invoke B2B Mail Client Adapter, it will request the Microsoft Identity Server to get an OAuth access token. Microsoft Identity Server will verify the credentials and provide the access token. Then, the B2B Mail Client Adapter will request the Microsoft Exchange Online with the access token and other information to access the resource. For details, refer to the illustration:

Note: B2B Mail Client Adapter uses Resource Owner Password Credential flow as Microsoft supports IMAP with the access token from this flow. This flow requires only one request for getting an access token when resource owner’s password is sent in the request.

OAuth 2.0 Feature Properties

To configure OAuth 2.0 feature into the B2B Mail Client Adapter, following properties are introduced into the oauth2.properties file:

Field	Description
oauth2_1.class_name	The implementation class for retrieving access token.
oauth2_1.display_name	The name displayed in the UI for the adapter configuration.
oauth2_1.provider	The provider of OAuth server. Note: Only MSExchange is supported.
oauth2_1.authorization_endpoint	The URL for the authorization.
oauth2_1.grant_type	The grant type of OAuth authorization. Note: Only password type is supported.
oauth2_1.client_id	The client id for OAuth authorization.
oauth2_1.client_secret	The client secret for OAuth authorization.
oauth2_1.scope	The permission scope for OAuth authorization. Note: It must be https://outlook.office365.com/IMAP.AccessAsUser.All for MSExchange.
oauth2_1.ssl_protocol	SSL protocol

Note: In the above table, "1" in oauth2_1 signifies OAuth configuration 1. The convention here is same as the LDAP configuration.

Note: Existing adapters which use basic authentication should still work without any change.

Client_secret which is used for getting the access token is encrypted and stored in the property file. When read, it is decrypted. Multi factor authentication needs to be turned-off for the user configured for the adapter and for OAuth’s password authorization flow. Refer to the example below for sample configuration:

oauth2_1.class_name = com.sterlingcommerce.woodstock.services.oauth2.OAuth2Authenticator
oauth2_1.config_name = Microsoft Exchange Online
oauth2_1.display_name = Microsoft Exchange Online
oauth2_1.provider = MSExchange
oauth2_1.authorization_endpoint = https://login.microsoftonline.com/<tenantt id>/oauth2/v2.0/token
oauth2_1.grant_type = password
oauth2_1.client_id = <client id of the application defined in Microsoft Azure>
oauth2_1.client_secret = <encrypted client secret generated for the application>
oauth2_1.scope = https://outlook.office365.com/IMAP.AccessAsUser.All
oauth2_1.ssl_protocol = TLS1.2

For more details, refer to Configure the OAuth 2.0 Feature in B2B Mail Client Adapter.