OAuth 2.0 authentication for Microsoft 365 mailbox integration

Hornbill supports Microsoft 365 mailbox integration using OAuth 2.0 (Modern Authentication). This method allows Hornbill to authenticate to Microsoft 365 without storing your account password. Instead, you authenticate directly with Microsoft Entra ID. After a successful authentication, Microsoft issues an access token and a refresh token, which Hornbill stores securely within a KeySafe record.

The Hornbill mail services reference this KeySafe record whenever they need to authenticate to Microsoft 365.

This guide describes:

How OAuth authentication works.
The role of KeySafe.
Microsoft 365 prerequisites.
Permissions and consent requirements.
How to create and authorize a KeySafe record.
Troubleshooting for common authentication issues.

This guide does not cover the configuration of inbound mail services or outbound SMTP Smart Hosts. For those topics, please refer to the generic email configuration documentation.

Before you begin

Before you configure a Microsoft 365 KeySafe record, ensure that you meet the following requirements:

You have a Microsoft 365 mailbox.
You have permission to authorize applications within your Microsoft 365 tenant, or a Microsoft 365 administrator can grant consent.
The mailbox is configured to allow OAuth 2.0 (Modern Authentication).
You know if the mailbox will be used for inbound mail, outbound mail, or both.

Note: Your Microsoft 365 administrator is responsible for configuring Microsoft Entra ID, Exchange Online, and Microsoft 365 tenant policies.

Understanding the authentication flow

flowchart TD
    A["Hornbill Mail Service"] --> B["KeySafe Record"]
    B --> C["Microsoft Entra ID"]
    C --> D["Access Token / Refresh Token"]
    D --> E["Exchange Online"]
    E --> F["IMAP4 / POP3 / SMTP AUTH"]

Microsoft 365 mailbox integration establishes the connection in two distinct stages.

Stage 1: Authentication

Authentication uses the OAuth 2.0 protocol. When you select Connect within a Microsoft 365 KeySafe record, the following process occurs:

Hornbill redirects you to Microsoft Entra ID.
You authenticate directly with Microsoft.
Microsoft evaluates the permissions requested by the Hornbill application.
Microsoft applies Conditional Access and authentication policies.
An administrator grants consent if required.
Microsoft issues OAuth tokens.
Hornbill securely stores the issued OAuth tokens within the Hornbill KeySafe record.

Hornbill never receives or stores your Microsoft account password.

Stage 2: Mailbox communication

After you authorize the KeySafe record, Hornbill mail services use the stored OAuth tokens whenever they authenticate to Microsoft 365. The mail services communicate using your chosen mail protocol, such as IMAP4, POP3, or SMTP AUTH.

Understanding KeySafe

A KeySafe record stores and manages the OAuth authorization used by Hornbill to authenticate to Microsoft 365. The KeySafe record performs the following tasks:

Initiates OAuth authentication.
Stores OAuth tokens securely.
Refreshes access tokens automatically.
Manages the OAuth lifecycle.
Allows you to reconnect an existing authorization if needed.

Mailbox configurations do not authenticate directly with Microsoft. Instead, they reference an authorized KeySafe record.

Create a Microsoft 365 KeySafe record

Follow these steps to create your record.

Steps

In Platform Configuration, navigate to the KeySafe option listed under the Security section.
Select the + Create New Key button.
From the Type dropdown, select the Microsoft 365 Mail Connector. The Sub Type is automatically set to OAuth2.
Enter a Title that makes it easy to identify this KeySafe record.
A description can be optionally added.
Select Create Key to add the new record.

Authorize the application

After your KeySafe record has been created, there will be an option to Connect. When you select Connect, Microsoft performs the following actions:

Authenticates your user account.
Evaluates the permissions that the Hornbill application requests.
Determines if an administrator must grant consent.
Applies any active Conditional Access policies.
Issues OAuth tokens if authentication and any required consent are successful.

After you complete these steps, the KeySafe record displays a status of Connected. The KeySafe record is now ready to be referenced by Hornbill mail services.

Permissions requested

Microsoft evaluates these delegated permissions during the OAuth authorization process. The permissions requested depend on the selected connector type.

Microsoft Office 365 Mail (Read/Write)

Permission	Purpose
IMAP.AccessAsUser.All	Access the mailbox using IMAP.
POP.AccessAsUser.All	Access the mailbox using POP3.
SMTP.Send	Send email using SMTP AUTH.
User.Read	Identify the authenticated user.
offline_access	Allow Microsoft to issue refresh tokens.

Microsoft Office 365 Mail (Read Only)

Permission	Purpose
IMAP.AccessAsUser.All	Access the mailbox using IMAP.
POP.AccessAsUser.All	Access the mailbox using POP3.
User.Read	Identify the authenticated user.
offline_access	Allow Microsoft to issue refresh tokens.

Additional Microsoft permissions

Your Microsoft 365 environment might show additional permissions for the Hornbill application registration. These can include permissions for Microsoft Graph and Office 365 Exchange Online. These permissions form part of the Hornbill application’s registration within Microsoft Entra ID and are managed by Microsoft. They may change over time and are not required to understand the Hornbill authentication process.

OAuth token lifecycle

After a successful authentication, Microsoft issues two types of tokens:

Access token

Hornbill presents the access token whenever it authenticates to Microsoft 365. Access tokens are short-lived for security purposes.

Refresh token

The refresh token allows Hornbill to obtain new access tokens automatically. This happens in the background without requiring you to sign in again.

You only need to reconnect the KeySafe record manually if:

The authorization expires.
An administrator revokes consent.
The application authorization is removed from Microsoft 365.
Microsoft requires a new authorization for security reasons.

Use the KeySafe record

After you connect the KeySafe record, you can select it in your Hornbill mail service configuration. The KeySafe record provides the OAuth authentication required by the configured mail services.

To finish setting up your email, refer to the following guides:

Shared Mailboxes (Inbound Mail Service)
Email Domains (SMTP Smart Host)
Email Protocol Support

Using Shared Mailboxes for Outbound Email

Hornbill can be configured to send email using a shared mailbox. However, the requirements for authenticating and sending mail from a shared mailbox are determined by Microsoft 365 and Exchange Online, and can vary depending on your organization’s configuration.

When configuring the SMTP Smart Host:

The Email Address field identifies the Microsoft 365 account used during SMTP authentication.
Ensure that the account and mailbox have the appropriate permissions required by your Microsoft 365 configuration.

Important: Exchange Online behavior for shared mailboxes is defined by Microsoft and may differ between tenants depending on licensing, delegated permissions (for example, Send As) and other Exchange Online settings. Before choosing a shared mailbox for outbound email, verify with your Microsoft 365 administrator that the authenticated account is permitted to send using the mailbox and that your intended authentication and sending scenario is supported by your Microsoft 365 configuration. For this reason, if you intend to use a shared mailbox for outbound email, we recommend validating the configuration with your Microsoft 365 administrator before completing the Hornbill Mail Service configuration.

Troubleshooting

“BAD User is authenticated but not connected”

This message typically indicates that the OAuth authentication stage was successful, but the mailbox connection failed.

This indicates that:

Microsoft authenticated the user successfully.
Microsoft issued valid OAuth tokens.
Exchange Online could not establish a session with the requested mailbox.

Because OAuth authentication completed successfully, you should investigate the issue within your Microsoft 365 environment.

Common causes to investigate

The following checks are intended to help identify common Microsoft 365 configuration issues that can prevent Exchange Online from establishing a mailbox connection after successful OAuth authentication. As these settings are part of Microsoft 365 rather than Hornbill, they should be validated by your Microsoft 365 administrator against your organization’s configuration and Microsoft’s current guidance.

The mailbox configuration.
The mailbox type (ensure it is a user or shared mailbox).
Protocol availability (ensure IMAP4, POP3, or SMTP AUTH is enabled).
Exchange Online authentication policies.
Conditional Access policies.
Administrator consent status.
Tenant-specific security restrictions.

Note: A working mailbox elsewhere in your tenant does not guarantee that this specific mailbox has the same configuration.

SMTP Error: 554 5.2.252 SendAsDenied

This error is returned by Exchange Online when the authenticated account is not permitted to send email using the configured mailbox.

If you are using a shared mailbox for outbound email, review the guidance in Using Shared Mailboxes for Outbound Email and verify that the authenticated account has the necessary permissions within your Microsoft 365 environment.

As mailbox permissions and delegated sending are managed by Microsoft 365, these settings should be validated by your Microsoft 365 administrator.

Frequently asked questions

Does Hornbill store Microsoft passwords?

No. You authenticate directly with Microsoft Entra ID. Hornbill only stores the OAuth tokens.

Does Hornbill support Modern Authentication?

Yes. Microsoft 365 mailbox integration uses OAuth 2.0.

Does Hornbill support Basic Authentication?

No. Microsoft has deprecated Basic Authentication for Exchange Online.

Has Microsoft deprecated IMAP4, POP3, or SMTP AUTH?

No. Microsoft deprecated Basic Authentication, but the mail protocols themselves remain supported when used with OAuth 2.0.

Does Hornbill communicate using Microsoft Graph?

No. After OAuth authentication is complete, Hornbill communicates with Microsoft 365 mailboxes using IMAP4, POP3 and SMTP AUTH rather than Microsoft Graph mailbox APIs.

Why do I only see an Enterprise Application and not an App Registration?

When using the Hornbill-provided Microsoft application, this is expected behavior.

The application itself is registered and managed by Hornbill. During the authorization process, Microsoft creates an Enterprise Application within your Microsoft Entra ID tenant to represent your organization’s authorized instance of that application.

As a result, you will typically see an Enterprise Application rather than an App Registration within your own Microsoft Entra ID tenant.

Which Microsoft 365 mailbox should I use?

Hornbill does not depend on a specific Microsoft 365 mailbox type. Instead, it requires a mailbox that supports the selected mail protocol (IMAP4, POP3 or SMTP AUTH) and OAuth 2.0 authentication.

Based on our experience, the vast majority of Hornbill deployments use one of the following:

A standard user mailbox.
A shared mailbox.

These examples are provided as guidance only and should not be considered an exhaustive or definitive list of compatible Microsoft 365 mailbox types.

Note: Hornbill determines compatibility based on the mail protocols and authentication methods supported by the mailbox, rather than its Microsoft 365 mailbox classification. Microsoft defines the mailbox types available within Microsoft 365, together with the protocols and authentication methods that each supports. These capabilities are independent of the Hornbill platform and may change over time. Regardless of the mailbox type you intend to use, you should refer to Microsoft’s current documentation to confirm that it supports the protocols and authentication methods required by your chosen mail integration.

Can I use a shared mailbox for outbound email?

Yes. However, the requirements for authenticating and sending mail from a shared mailbox are determined by Microsoft 365 and may vary depending on your Exchange Online configuration. Before using a shared mailbox for outbound email, verify that it supports your intended authentication and sending scenario. See Using Shared Mailboxes for Outbound Email above.

When should I reconnect a KeySafe?

You should only reconnect if the authorization expires, is revoked, or if Microsoft requires a new authorization.

Can one KeySafe record be used by multiple mail services?

Yes. A KeySafe record represents an OAuth authorization for a Microsoft 365 account and can be referenced by multiple Hornbill mail services. For example, the same KeySafe record can be used by both an Inbound Mail Service and an Outbound SMTP Smart Host, provided they authenticate using the same Microsoft 365 account. Create separate KeySafe records only when different Microsoft 365 accounts or different connector types are required.

Next steps

Once your Microsoft 365 KeySafe record has been authorized, you must configure the Hornbill mail services.

See the following resources:

Documentation

{{docApp.title}}

How can we help?

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.

{{resultItem.title}}

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

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

{{group.title}}