Documentation

    {{docApp.userSession.userId}}
    {{docApp.userSession.userName}}
    {{docApp.userSession.email}}
    Issuer : {{docApp.userSession.issuerInstance}}
    Expires : {{new Date(docApp.userSession.validUntil).toLocaleDateString()}}

{{docApp.title}}

{{docApp.description}}

How can we help?

{{docApp.searchError}}
{{product.name}}

Searching in {{docApp.searchFilterBySpecificBookTitle}}

{{docApp.searchResultFilteredItems.length}} results for: {{docApp.currentResultsSearchText}} in {{docApp.searchFilterBySpecificBookTitle}}
Search results have been limited. There are a total of {{docApp.searchResponse.totalResultsAvailable}} matches.

You have an odd number of " characters in your search terms - each one needs closing with a matching " character!

{{docApp.libraryHomeViewProduct.title || docApp.libraryHomeViewProduct.id}}

{{docApp.libraryHomeViewProduct.description}}

  1. {{book.title}}

{{group.title || group.id}}

{{group.description}}

  1. {{book.title}}

{{group.title}}

{{book.title}}
More...

Configure OAuth2 authentication for Microsoft Office 365 mailbox integration

To enable Hornbill to use the OAuth 2.0 protocol for authenticate to Microsoft Office 365, a Hornbill key that contains the OAuth authentication token needs to be created in Keysafe. This key is then used when configuring the mailbox service component.

The key steps for mailbox integration include:

  1. Create a key in Hornbill Keysafe
  2. Generate an OAuth authentication token
  3. Configure the Mail Service Component
    1. Outbound Mail Routing Smart Host
    2. Inbound Mail Service

Information

For this process, it is highly advisable to ensure that no Outlook, Hotmail, or any Microsoft-linked account is currently logged in, and use Incognito/InPrivate/Private Mode or Window in the browser where this operation is being performed.

Create a key in Hornbill Keysafe

In the Hornbill KeySafe, create a key using the type Microsoft Office 365 Mail Connector. Once the key is given a title, and optionally a description, the key can be created.

Generating the oAuth authentication token

Clicking the Connect button within the key’s details form initiates the authentication between KeySafe and the Microsoft Office365 server. The process follows these steps, which will take place in MS context:

  1. Authenticate on O365 using an MS account: this would be an account with sufficient rights to access the O365 mailbox (see Notes below). This step can involve a multi factor authentication mechanism (depending on how O365/Azure environment is configured).
  2. Grant permission to delegate access rights required by Hornbill (if requested as such by MS - this step might not be necessary, depending on o365 configuration, in which case this step is bypassed)
  3. Approval required: grant permissions for the Hornbill connector to access the mailbox on O365 (if requested as such by MS - this step might not be necessary, depending on O365, in which case this step is bypassed). The approval request is created automatically in O365/Azure and details on how to approve the Hornbill connector, can be found here: “How would the Office365 administrator approve permission requests”

Note

If approval is required for the Azure app (Step 3), then Steps 1-2 will have to be performed again to complete the Connect operation and generate the authentication token. In this case, the step sequence becomes: S1, S2 (if required), S3 - app is approved -, S1, S2 (if required).

The following API\Permissions are required for the Microsoft Office 365/Azure app

  • 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

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,

  1. 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 utilize Use SMTP SmartHost as the Outbound Routing Mode, please see the section #Outbound Mail Services via Smart Host for proper configuration of options.
  2. Once the route has been created, the next step to be created is the Shared Mailboxes.
  3. 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

References

  • How would the Office365 administrator approve permission requests
  • Microsoft’s [POP, IMAP, and STMP settings]
  • [Deprecation of Basic Authentication in Exchange Online]

Troubleshooting

In the event that problems occur during the setup process. These are some of the problems that have been encountered, and the solutions to them.

The credential window and the consent window are endlessly presented.

Description:: After connecting the keysafe entry to the desired email account, and the admin consenting to the operation, Microsoft once again asks for the desired email address and the consent. The whole operation is repeated once again.
To solve this issue, the following steps are suggested:

  1. Ensure that the “Hornbill Office365 Mail Connector” is not present in the list of Enterprise Application
  2. Ensure that the target Keysafe entry is unconnected.
  3. Temporarily connect the keysafe entry to a global admin account with an empty mailbox.
  4. Setup the IMAP4/POP3 email service with the global admin account.
  5. Ensure that the email can get into the mailbox.
  6. Once successful, revoke the keysafe entry and connect to the desired email address.
  7. Setup the all the necessary connectors as they should now be properly enabled.

No emails are being received, and the following error always appears in the EspMailImporter.log.

Description: Upon completing the connection and setup of the shared mailbox, the following error “serverResponse: aaac BAD User is authenticated but not connected.” is logged in the EspMailImporter.log log file. Mail is also not being delivered to the shared mailbox.

  • To solve this issue, the following steps are suggested:
  1. Ensure that the “Hornbill Office365 Mail Connector” is not present in the list of Enterprise Application
  2. Ensure that the target Keysafe entry is unconnected.
  3. Temporarily provide the desired email account with the following azure role/privileges:
    • Application Admin
    • Exchange Admin
  4. Connect the target Keysafe entry to the desired email account
  5. Setup the IMAP4/POP3 email service with the desired email account/target Keysafe entry.
  6. Ensure that the email can get into the mailbox.
  7. Once successful, revoke/remove the azure role/privileges:
    • Application Admin
    • Exchange Admin
  • Version {{docApp.book.version}}
  • Node {{docApp.node}} / {{docApp.build}}
In This Document