How to configure OAuth2 Authentication for Microsoft Office 365 Mailbox integration
Introduction
In order to enable Hornbill to use OAuth 2.0 protocol to authenticate to Microsoft Office 365 for mailbox integration, a Hornbill Keysafe item is required that contains the OAuth 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:
- Create and link a Hornbill Keysafe
- Configure the Mail Service Component, either or both
- Outbound Mail Service via Smart Host Configuration
- Inbound Mail Service Component
- The POP3 service -or-
- The IMAP4 service
NOTE: Ensure that no Outlook, Hotmail, or any Microsoft-linked account is currently logged in. It is advisable to use Incognito/InPrivate/Private Mode or Window in the browser in performing this operation.
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 OAuth authentication token.
The following API\Permissions are required for the Microsoft Office 365 OAuth Keysafe type
Office 365 Exhchange OnLine
- Mail.Read - Read User Mail
- Mail.Read.All - Read User and Shared Mail
- Mail.Read.Shared - Read User and Shared Mail
- Mail.Send - Send Mail as a User
- Mail.Send.All - Send Mail on behalf of others
- Mail.Send.Shared - Send Mail on behalf of others
- USer.Read - Read Users Profiles
Connect
Clicking the Connect button on the Key Details form, initiates the authentication of KeySafe to Microsoft Office365 servers. 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.
- Page requesting for email address of account to use
- Page requesting the credentials for the account. This may include other multi-factor authentication mechanism.
- 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 account, as it will be used later on. |
| Microsoft requests authentication | 
|
| 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.
- The critical information is the Domain Name. This entry should be the same Office365 domain that Microsoft has assigned, (ie testdomain.onmicrosoft.com). The rest of the options can be set as indicated by the wiki-page Email Domains. If one desires to utilise Use SMTP SmartHost as the Outbound Routing Mode, please see the section #Outbound Mail Services via Smart Host for proper configuration of options.
- Once the route has been created, the next step to be created is the Shared Mailboxes.
- Then link an outbound mail route.
- A key point to remember when defining the link email address, use the email address linked to the Office365 account as the default address.
- After defining the linked address, proceed to create the desired #Inbound Mail Services to allow Hornbill to retrieve emails from the Office365 account.
Outbound Mail Services via Smart Host
To allow Hornbill to send emails as the linked Office365 account, SMTP SmartHost must be configured. To perform that, the following entries must have the indicated values.
| Entry | Value |
|---|---|
| Host | smtp.office365.com |
| Port | 587 |
| Encryption | TLS(Transport Layer Security - RFC2595) |
| Authentication Method | OAuth2 |
| Email Address | The email address that was provided to Microsoft during KeySafe entry connection. See image |
| Credentials | The keysafe entry that was created above |
- BOLD VALUES are exact values for the entries.
- Italic values are values to be supplied.
- Clicking the Test Connection button would check if the values are valid.
- See [Microsoft's page for reference].
Inbound Mail Services
To allow Hornbill to retrieve emails addressed to the linked Office365 account, either POP3 or IMAP4 service must be correctly defined. Please select one of the services. It is possible for the system to be configured to retrieve email from more than one Office365 account, provided that each account will require its own KeySafe entry. Even though it is possible, the system might not be able to fully identify the source account.
POP3 Services
To configure the POP3 service, the following must be the values for the entries,
| Entry | Value |
|---|---|
| Service | POP3 |
| Server | outlook.office365.com |
| Port | 995 |
| Encryption | TLS(Transport Layer Security - RFC2595) |
| Authentication Method | OAuth2 |
| Username | The email address that was provided to Microsoft during KeySafe entry connection. See image |
| Credentials | The keysafe entry that was created above |
- Clicking the Test Connection button would check if the values are valid.
- See [Microsoft's page for reference].
IMAP4 Services
To configure the IMAP4 service, the following must be the values for the entries,
| Entry | Value |
|---|---|
| Service | IMAP4 |
| Server | outlook.office365.com |
| Port | 993 |
| Encryption | TLS(Transport Layer Security - RFC2595) |
| Authentication Method | OAuth2 |
| Username | The email address that was provided to Microsoft during KeySafe entry connection. See image |
| Credentials | The keysafe entry that was created above |
- Clicking the Test Connection button would check if the values are valid.
- See [Microsoft's page for reference].