Troubleshooting common issues related to the Oauth 2.0 integration with incoming mail handlers in Jira/Service Management
Platform Notice: Server and Data Center Only. This article only applies to Atlassian products on the server and data center platforms.
Since Jira 8.10.0 (or in Service Management 4.10.0), it is possible to configure Jira or Service Management incoming Mail Handlers using the Oauth 2.0 integration instead of the Basic Authentication which will be eventually deprecated by Google and Microsoft.
Setting up a mail handler with the Oauth 2.0 authentication consists of 2 main steps which are explained in details in the documentation Integrating with OAuth 2.0 (Jira 8.10.x-8.21.x)/Configure an outgoing link (Jira 8.22.x+) (and in the community discussion Why can't I connect to Microsoft with oAuth2.0 setup):
- 1st Step: Configuring an Oauth 2.0 integration in the page ⚙ > System > Oauth 2.0 (in Jira 8.10.x-8.21.x) or ⚙ > System > Application links (in Jira 8.22.x+)
- 2nd Step: Configuring either:
- A Jira Mail Handler (in ⚙ > System > Incoming Mail)
- A Jira Service Management Mail Handler (in Project Settings > Email Requests)
We have identified 3 main categories of issues you might run into while configuring this integration. Each of these issue has a dedicated KB article (mentioned in the table below) which explains how to troubleshoot and resolve them.
Most common types of Oauth 2.0 issues and their relevant knowledge base articles
|Type of issue||Description||KB article|
|Issues related to opening/viewing the Oauth 2.0 page||For any issue related to the Oauth 2.0 page (for example: the page is missing, or is blank, or can't be accessed), refer to the article from the "KB article" column.||The OAuth 2.0 configuration page in Jira is either missing or blank/empty|
|Issues related to the configuration of the Oauth 2.0 integration (connection test failure)|
If after configuring the Oauth 2.0 integration, the connection test fails on Oauth 2.0 page (as illustrated in the screenshot below), then refer to the article from the "KB article" column.
|The connection test of the OAuth 2.0 integration fails with the error "the connection has failed. check the application logs for details"|
|Issues related to the configuration of the mail handler (authorization or connection test failure)|
If the connection test of the Oauth 2.0 integration is successful, but the authorization or connection test of the Mail Handler fails (as illustrated in the screenshots below), then refer to the article from the "KB article" column.
|Jira and/or Service Management Mail Handlers cannot be configured using Oauth 2.0 - The authorization or connection test fails|
Providing data to Atlassian Support
If none of the KB article listed above helped resolve the Oauth 2.0 issue you are facing, please make sure that you followed all the steps mentioned in the documentation Integrating with OAuth 2.0 (Jira 8.10.x-8.21.x)/Configure an outgoing link (Jira 8.22.x+) (and in the community discussion Why can't I connect to Microsoft with oAuth2.0 setup in case you are using Microsoft Office 365/Exchange).
You can also reach out to Atlassian Support via this link. To help the Atlassian support team investigate the issue faster, you can follow the steps below and attach all the collected data to the support ticket raised with Atlassian:
- Collect the following screenshots
- Go to the page ⚙ > System > Oauth 2.0 (in Jira 8.10.x-8.21.x) or ⚙ > System > Application links (in Jira 8.22.x+), click on the Edit button next to the Oauth 2.0 integration and take a screenshot of the whole page
- Take a screenshot showing what happens when you try to authorize or test the connection for the mail handler using Oauth 2.0:
- For a Jira Mail Handler, take a screenshot of the page ⚙ > System > Incoming Mail > Mail Server > Edit
- For a Service Management Mail Handler, take a screenshot of the page Project Settings > Email Requests
- Generate a support zip by making sure to tick the option Thread Dumps when you generate it.
- If you are using Jira Data Center, please generate a support zip from each Jira node
- Attach to the support ticket:
- The screenshots
- The support zip(s)