Troubleshooting most common issues related to the Oauth 2.0 authentication with incoming mail handlers (or the outgoing mail server) in Jira and JSM
Platform notice: Server and Data Center only. This article only applies to Atlassian products on the Server and Data Center platforms.
Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Summary
The Oauth 2.0 authentication method has been recently introduced for both the Incoming Mail and Outgoing Mail functionalities or Jira and JSM (Jira Service Management):
- Since Jira 8.10.0 (or JSM 4.10.0), it has become possible to configure a Jira (or JSM) Incoming Mail Handlers using the OAuth 2.0 Authentication instead of the Basic Authentication which will be eventually deprecated by Google and Microsoft.
- Since Jira 9.2.0 (or JSM 5.2.0), it has become possible to configure Jira with an Outgoing Mail Server using Oauth 2.0
Setting up a mail handler (or outgoing mail server) with the Oauth 2.0 authentication consists of 2 main steps which are explained in detail in the documentation Integrating with OAuth 2.0 (for Jira 8.10.x-8.21.x) and Configure an outgoing link (for Jira 8.22.x+):
- 1st Step - Configuring an Oauth 2.0 integration
- Via the the page ⚙ > System > Oauth 2.0 for Jira 8.10.x-8.21.x
- Via the page ⚙ > System > Application links for Jira 8.22.x+
- 2nd Step - Configuring the Mail Server
- In case of Incoming Mail Handler:
- Via the page ⚙ > System > Incoming Mail, in case of a Jira Mail Handler
- Via the page in Project Settings > Email Requests, in case of Jira Service Management (JSM) Mail Handler
- In case of Outgoing Mail Server:
- Via the page ⚙ > System > Outgoing Mail
- In case of Incoming Mail Handler:
Note that, if you are using either Microsoft US Government DoD or US Government GCC High account account, the configuration is slightly different than for other types of Microsoft accounts. This configuration is explained in the article How to configure a Microsoft US DoD or GCC High account with a Jira or a Service Management mail handler using Oauth 2.0.
We have identified 5 main categories of issues you might run into while configuring these Mail Servers with the Oauth 2.0 authentication. Each of these issues has a dedicated KB article (mentioned in the table below) that explains how to troubleshoot and resolve them.
Most common types of Oauth 2.0 issues and their relevant knowledge base articles and bug tickets
| Type of issue | KB Article |
|---|---|
| Issues related to the Oauth 2.0 Application link configuration | Failure to open/view the Oauth 2.0 configuration page Failure to configure or test an Oauth 2.0 application link (connection test failure) |
| Issues related to Incoming Mail functionalities (Jira or JSM Mail Handlers) using Oauth 2.0 | A Jira or JSM Mail Handler fails to process new incoming emails when configured with Oauth 2.0 |
| Issues related to the Outgoing Mail (notification) functionality using Oauth 2.0 | Failure to configure an Outgoing Mail Server using Oauth 2.0 (connection test failure) Outgoing mail not working on SMTP server configured to use OAuth 2.0 as authentication method |
Providing data to Atlassian Support
If none of the KB articles listed above helped resolve the Oauth 2.0 issue you are facing, you can 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 (or outgoing mail server) 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
- In case of the Outgoing Mail Server, take a screenshot of the page ⚙ > System > Outgoing Mail > Edit
- 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
- Generate a HAR file, in case you are failing to configure the OAuth 2.0 integration, the Mail Handler, or the Outgoing Mail Server
- Attach to the support ticket:
- The screenshots
- The HAR file
- The support zip(s)