Fixing IMAP and User error with OAuth 2.0 and Jira Data Center

Summary

For a successful integration of a Jira (or Service Management) incoming mail handler using OAuth 2.0 with an external mail server (Microsoft, Gmail, etc.), it is essential that the mailbox user has the correct permissions and that the IMAP protocol is enabled.

Diagnosis

Testing the configuration with the Microsoft Remote Connectivity Analyzer

Microsoft has a very useful online tool called Microsoft Remote Connectivity Analyzer, which allows users to test the OAuth 2.0 integration with any mailbox and with IMAP.

• This tool is not available for GCC High environments

You can run the test by:

• Setting the Authentication type to Modern Authentication (OAuth)

• Set the field Modern Authentication (OAuth) credentials as the user who is supposed to authorize the mailbox in Jira, and click on Sign In

• In case the mailbox that is used in the Jira Mail server configuration is different, please set this email address in the field Alternate mailbox (optional)

Example of a successful test

If the test is successful, check Fix OAuth 2.0 Issues in Jira Mail Handlers for Data Center for other possible causes and solutions.

Cause

If the test fails, it indicates that:

• Either the wrong user is authorizing the mailbox

• Or the IMAP protocol is disabled for the mailbox

Your mailbox might not have the right permissions in Microsoft Office 365/Exchange

If the mailbox used by the Mail Handler is from a different user account than the user who is logging into the Microsoft portal to authorize it (Scenario 1), or if it is a shared mailbox (Scenario 2), this setup only works if the user has delegated permissions (Full Access) on:

• The mailbox from the other account (Scenario 1)

• Or the shared mailbox (Scenario 2)

If such permission is not granted on the mailbox (from the other account or the shared mailbox), then the authorization process will fail.

For more information about this root cause, please refer to the KB article Jira Mail Handler and Service Management Mail Handler can't be configured using OAuth 2.0, due to incorrect mailbox permission.

The IMAP (or POP) protocol is disabled at the mailbox level in Microsoft Office 365/Exchange

Ensure that the IMAP or POP protocol is enabled for your mailbox. This is necessary for configuring the mail server in Jira.

For more information about this root cause, please refer to the KB article Configuring JSM Mail Handlers: IMAP/POP Required for OAuth 2.0

Solution

Your mailbox might not have the right permissions in Microsoft Office 365/Exchange

When logging into the Microsoft portal, make sure you have full access to the mailbox (or shared mailbox).

In Office 365, this can be done as shown below, as explained in Microsoft's documentation, Accessing other people's mailboxes in Microsoft 365:

• Log in to the Exchange Control Panel at https://outlook.office365.com/ecp

• Look for the mailbox for which you need to change the permissions:

  • For Scenario 1 (other user account mailbox), go to Recipients > Mailboxes

  • For Scenario 2 (shared mailbox), go to Recipients > Shared

• Find the mailbox, and select the Edit option

• After the pop-up window opens, go to Mail delegation and add the user under Full Access

For more information on how to do it, refer to the KB article Jira Mail Handler and Service Management Mail Handler can't be configured using OAuth 2.0, due to incorrect mailbox permission.

The IMAP (or POP) protocol is disabled at the mailbox level in Microsoft Office 365/Exchange

Ensure that IMAP (or POP) is enabled at the mailbox level:

• If a Microsoft Exchange mailbox is a user, enable IMAP (or POP) for the mailbox by following the instructions in

  Enable or disable POP3 or IMAP4 access to mailboxes in Exchange Server

• If an Office 365 mailbox is used, enable IMAP (or POP) for the mailbox by following the instructions in

  How to enable or disable POP3 or IMAP for a user in Office 365

For more information, refer to the KB article Configuring JSM Mail Handlers: IMAP/POP Required for OAuth 2.0

If the above doesn't fix the issue, check Fix OAuth 2.0 Issues in Jira Mail Handlers for Data Center for other possible causes and solutions.