How to configure OAuth2 Authentication for Microsoft Office 365 Mailbox integration

Introduction

In order to enable Hornbill to use OAuth2 protocol to authenticate to Microsoft Office 365 for mailbox integration, a Hornbill Keysafe item is required that contains the OAuth2 authentication token. This is then used to configure any of Hornbill's integration components, namely the following

• Email's Outbound Mail Routing Smart Host Configuration, -or-
• Inbound Mail Service Components of the Shared Mailboxes.

The steps to configure this is the following:

1. Create and link a Hornbill Keysafe
2. Configure the Mail Service Component, either
   1. Inbound Mail Service Component
      • The POP3 service -or-
      • The IMAP4 service
   2. Outbound Mail Service via Smart Host Configuration

Hornbill Keysafe

As instructed by the Hornbill KeySafe page, create a keysafe whose type is Microsoft Office 365 Mail Connector. Once the keysafe is named and created, invoke the Connect button to initiate the authentication and generation of the OAuth2 authentication token. A new webpage should appear originating from Microsoft requesting the authentication/credentials of the account that will be used as the point of integration with Hornbill.

The following can be the series of steps.

1. Page requesting for email address of account to use
2. Page requesting the credentials for the account. This may include other multi-factor authentication mechanism.
3. Page requesting permission to delegate rights from the account to the application. It can be any of the indicate pages.
   • If an administrator permission is required then the actions in the page "How would the Office365 administrator approve permission requests" needs to be performed.

NOTE: Once administrator permission is given. Performing the same steps above would NOW be possible to complete.

Different pages that Microsoft can provide

Microsoft requests email address to be used	NOTE: Please take note of the email address, of the Office365 email account, as it will be used later on.
Microsoft requests authentication	Can include other multi-factor authentication mechanisms
Microsoft asks user for permission to delegate the access rights that Hornbill requires	These are some of the requests that Microsoft can request This page indicates that the administrator is requested to provide the permission. The administration would then be required to do some action.
Microsoft sometimes indicates the return to originating application/website typically after requesting permission from the administrator.

Configuring Mail Service Components

Once an Office365 email account is integrated to Hornbill, the email account can be used to send email out or receive email from other entities, that can be processed by Hornbill. To make this configuration, the first requirement is to create an Email Domains.

shared mailbox. This shared mailbox is to represent the Office365 email account. This can be created as described by this Shared_Mailboxes wiki page.

Inbound Mail Services

In configuring the inbound emails, the user has to decide what communication protocol it is going to use to obtain email stored in the Office365 email account for Hornbill processing. Both protocols can provide the same functionality, and differs only in their original intent. In order to setup the connection a shared mailbox is needed.