Jira Mail Handlers or Service Management Mail Handlers cannot be configured using Oauth 2.0 - The authorization or connection test fails
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
Due to the complexity of integrating a Jira (or Service Management) incoming mail handler using Oauth 2.0 with an external mail server (Microsoft, Gmail...), there can be a lot of reasons why this integration breaks. The problem might either come from a misconfiguration on the Jira application side, the Mail Server side, or on the network side.
The common symptoms that are observed in the Jira UI are illustrated in the screenshots below (click on the screenshot link below to view the screenshots):
This KB article lists of the root causes which have been identified so far, and which are known to prevent Jira Administrators from successfully configuring, authorizing and testing either of the 2 types of Mail Handlers"
- a Jira Service Management (JSM) Mail Handler from the page Project Settings > Email Requests
- a Jira Mail Handler from the page ⚙ > System > Incoming Mail
Environment
Jira Service Management 4.10.0 / Jira 8.10.0 and higher
Diagnosis
Checking the scopes
The first thing to check is the scope configuration in the Oauth 2.0 integration, which is located
- in ⚙ > System > Oauth 2.0 for Jira versions up to 8.21.x
- or in ⚙ > Applications > Application Links for Jira versions from 8.22.0
For more for information on how to check the scopes, please expand the section below:
Testing the configuration with the Microsoft Remote Connectivity Analyzer
Microsoft has a very useful online tool called Microsoft Remote Connectivity Analyzer, which allows user to test the Oauth 2.0 integration with any mailbox and with IMAP.
You can run the test by:
- setting the Authentication type to Modern Authentication (Oauth)
- signing in in the field Modern Authentication (OAuth) credentials as the user who is supposed to authorize the mailbox in Jira
- in case the mailbox that is used in the Jira Mail Server configuration is different than the user who is authorizing it, please set this email address in the field Alternate mailbox (optional)
- If the test fails with some error, then it is an indication that:
- either wrong user is authorizing the mailbox (please refer to Root Cause 3)
- or the IMAP protocol is disabled for the mailbox (please refer to Root Cause 2)
You can refer to the Expand section below for an example of successful and failed tests:
Checking the Jira and Jira Service Management (JSM) version
Different Jira and JSM versions support different mail protocols (IMAP, POP, SMTP) with the Oauth 2.0 authentication method, and different type of Microsoft Accounts (Microsoft Worldwide/GCC accounts, US Government DoD, US Government GCC High accounts...).
You can expand the section below to check what is supported, based on the Jira/JSM version you are using.
Checking the account used to authorize the mailbox
Another thing to check is the permission of the account used to log into Microsoft (or Google) during the mailbox authorization process.
You can expand the section below for more information on how to check this.
Verifying that the mailbox is granted a license
If the mailbox is not granted a license on the mail server side (for example Microsoft), the Mail Handler configuration will fail.
You can expand the section below to check if a mailbox was granted a license in the case of Microsoft.
Checking the Jira application logs
Once you've already checked the points listed above, the next steps is to check the Jira logs (in either the file atlassian-jira.log or atlassian-jira-incoming-mail.log).
You can expand the section below to get an idea of which errors you should be looking for in these logs, and which root cause(s) might be relevant based on the error.
Generating a HAR file while replicating the issue (Jira Data Center Only)
If the Jira application is configured with at least 2 nodes running behind a Load Balancer, then we recommend generating a HAR file or using the Browser Network tool to make sure that the user configuring the Mail Handler stays on the same node the entire time. If you observe that at least one of the requests sent from the browser to the Jira application is redirected to a different node, then the configuration of the Mail Handler will likely fail, and the Root Cause 13.
You can expand the section below to see an example where one of the request is incorrectly redirected to a different node after the authorization process, ultimately causing the Mail Handler configuration to fail.
Cause
Root Cause 1 - Incorrect scopes are used in the Oauth configuration in Jira > ⚙ > System > Oauth 2.0
An incorrect set of scopes is configured in the Oauth 2.0 integration, which is located:
- in ⚙ > System > Oauth 2.0 for Jira versions up to 8.21.x
- or in ⚙ > Applications > Application Links for Jira versions from 8.22.0
Root Cause 2 - The IMAP (or POP) protocol is disabled at the mailbox level in Microsoft Office 365/Exchange
IMAP (or POP, depending on which protocol is used to configure the mail server in Jira) is disabled for the mailbox.
For more information about this root cause, please refer to the KB article Jira Service Management Mail Handler cannot be configured using Oauth 2.0 due to when IMAP (or POP) being disabled for the mail box.
Root Cause 3 - The Mailbox is configured with incorrect delegated 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), such configuration will only work if this user is granted 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 cannot be configured using Oauth 2.0, due to incorrect mailbox permission.
Root Cause 4 - No license was provided to the Microsoft account to access the mailbox that belongs to this account
There is no license provided for the Microsoft account to access the mailbox that belongs to this account.
For more information about this root cause, please refer to the KB article Jira Mail Handler and Service Management Mail Handler cannot be configured using Oauth 2.0, due to Microsoft License issue.
Root Cause 5 - The Microsoft Mailbox language is not set to English and we are hitting a Jira bug
To check if you are impacted by the Jira bug, please refer to the public bug ticket - JSDSERVER-7058Getting issue details... STATUS .
Root Cause 6 - Office 365 configuration to allow IMAP over OAuth 2.0 is incomplete as Client Access Rules is missing "IMAP4" rule
For more information about this root cause, please refer to the sections Cause 1 of the KB article IMAP fails with A3 BAD User is authenticated but not connected error in Jira server integrated with Office365.
Root Cause 7 - There is a firewall blocking traffic from the Jira Server to the internet, or to specific ports (for example 993 for IMAPS)
To check if this root cause is relevant, please reach out to your firewall admin and check if there is some firewall configuration:
- blocking the Jira application from reaching the internet (the Jira application needs to have access to its own base URL, but also to the Mail Service Provider)
- blocking any port such as 110 (for POP), 995 (for SECURE_POP), 143 (for IMAP), 993 (for SECURE_IMAP).
It is important to note that running the telnet command with the mail server hostname and port is not sufficient to verify whether there is a network/firewall issue or not. Even if the telnet command is successful, it does not mean that there isn't some firewall configuration that is blocking Jira from accessing the mail server. The telnet command will only open a socket, but will not verify if a protocol is allowed or not on the selected port.
Root Cause 8 - The application was created in Azure with the "single-tenant" account type
When configuring an Oauth 2.0 integration with the default values provided by Jira for the 2 fields Authorization endpoint and Token endpoint, we recommend using the support account type of the application needs to be set to Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox).
If the support account type is set to "single-tenant", then it will be impossible to configure an incoming mail handler, and the Authorization step will fail.
If your organization only allows the "single-tenant" support account type, then it will be necessary to change the 2 fields Authorization endpoint and Token endpoint in the Oauth 2.0 configuration page. Please refer to the section Solution for Root Cause 8.
Root Cause 9 - The Outlook mail account is a Microsoft US Government DoD or US Government GCC High account
Depending on the type of Mail Handler you need to configure (Jira vs JSM), the versions that support these types of accounts are different:
- the Jira Mail Handler supports these Microsoft accounts:
- in Jira Server and Data Center
- in any Jira version from 8.10.0
- the Jira Service Management (JSM) Mail Handler supports these Microsoft accounts:
- in JSM Server and Data Center
- in any JSM version from JSM 4.22.0 for the Data Center license, and 4.22.2 for the Server license
If you need to configure such type of Microsoft account, please make sure that you are using the license and version that support it.
There are various scenarios where the configuration of this type of account might not work. For example:
- If you are trying to configure a Jira Mail Handler with this type of account, it is necessary to use outlook.office365.us as the hostname in the Mail Server configuration, or this configuration with fail
- If you are trying to configure a JSM Mail Handler with this type of account, please note that you need to use JSM on 4.22.0 or any higher version, since only 4.22.0 support GCC accounts as per the feature request - JSDSERVER-6998Getting issue details... STATUS
Root Cause 10 - The combination of Oauth 2.0 with the POP protocol is unsupported in the Jira version in use, or is misconfigured
The support for the POP protocol along with Oauth 2.0 for the Jira Mail Handler feature was introduced in the Jira versions 8.15.0, 8.13.4, 8.5.12, as per this feature request: - JRASERVER-72033Getting issue details... STATUS
If the Jira version that is used is lower than the versions listed in the feature request, then:
- The combination of Oauth 2.0 and POP is not supported
- It will not be possible to configure a Jira Mail Server in ⚙ > System > Incoming Mail
- The error "Protocol error. Connection is closed. 10" will be thrown in the UI when clicking on Test Connection
If the Jira version that is used is higher than the versions listed in the feature request, then:
- The combination of Oauth 2.0 and POP will be supported
- It will be possible to configure a Jira Mail Server in ⚙ > System > Incoming Mail
- Note that it will be required to tick the option Use two line authentication format in the Mail Server configuration before clicking on Test Connection. If this option is not ticked, then the error "Protocol error. Connection is closed. 10" will be thrown in the UI when clicking on Test Connection
Root Cause 11 - Incorrect Microsoft user credentials are cached in the browser while authorizing the mailbox
We have see that, in some rare cases, incorrect MS user credentials are cached in the browser.
For example, when authorizing a mailbox to configure a Jira (or JSM) incoming mail server, this user is redirected to the MS login page. Even though this user is trying to log into MS as user1, for some reason this user is logged as user2. Even though the authorization processes goes through without any error, the following behavior might happen if the user2 is actually not allowed to connect to the mailbox via Oauth 2.0:
- The connection test in the JSM Mail Handler configuration page will fail with the error below:
- The connection test in the Jira Mail Handler configuration page will be successful. However, when configuring a Mail Handler linked to that Mail Server and testing the Mail Handler, the error BAD User is authenticated but not connected might be thrown:
Root Cause 12 - The beta version of the JSM multi-channel feature is used
As per the Jira Service Management 4.22.x release notes, JSM 4.22.0 introduced the ability to configure multiple mail channels (mail handlers) within the same Service Desk project.
A beta version of this feature was included in JSM 4.18 and could be enabled by adding the dark feature sd.multi.incoming.email.support.enabled, as per the documentation Adding multiple email channels for creating requests. This beta version was incomplete and only meant for customers to test it and provide feedback on it. One known issue with this feature is that if at least 2 mail channels are configured using Oauth 2.0 as the authentication method, the 2nd channel will fail to be properly configured, and the following will be observed:
- the status of this channel will show as "Failed"
the following error will be thrown in the Jira Incoming Mail Logs:
2022-10-12 08:02:36,237+0000 ERROR [] Caesium-1-3 ServiceRunner Exception when MailPullerWorker pulls emails: com.atlassian.jira.internal.mail.processor.errors.MailConnectionException: OAuth token not defined for connection. OAuth Authorisation required. at com.atlassian.jira.internal.mail.processor.feature.puller.MailPullerWorker.lambda$getMailServerPassword$2(MailPullerWorker.java:250) [jira-email-processor-plugin-4.20.11-REL-0003.jar:?] at io.atlassian.fugue.Either$Left.fold(Either.java:586) [fugue-4.7.2.jar:?]
Note that this issue is not replicable in the final version of this feature which was included in JSM 4.22.0, so we highly recommend to upgrade to this version to avoid this issue.
Root Cause 13 - (Jira Data Center Only) Jira is running on a cluster of nodes and session stickiness is not respected
To configure a Jira or JSM Mail Handler with Oauth 2.0, it is necessary that the user configuring it stays on the same Jira node the whole time. If the user is incorrectly redirected to another after logging into the Mail Server to perform the authorization process, the configuration of the Mail Handler will fail.
There can be 2 reasons why a user is incorrectly redirected to another node after the authorization process:
- Reason 1 - The Load Balancer was not correctly configured to ensure session stickiness as per the documentation Jira Data Center Load Balancer examples.
- Instead of keeping the same user session on the same node, it incorrectly redirects this user to another node.
- Reason 2 - The Load Balancer is configured to redirect REST API traffic to a specific node, but is not making the distinction between External and Internal API requests, as per the documentation Traffic distribution with Atlassian Data Center
- Instead of keeping the same user session on the same node, it incorrectly redirects the internal REST API request to a dedicated node, instead of redirecting it to the node the user was on
Root Cause 14 - The client secret of the Azure application has expired
As explained in Configure an outgoing link, to configure Jira with Oauth 2.0 using Microsoft, it is necessary to first configure an application on the Azure side along with a Client Secret. Since Client Secrets are configured with an expiration date, the Jira (or JSM) mail handler will stop pulling new emails since it will be blocked from connecting to the mailbox via the Oauth 2.0 authentication.
One way to check if the secret has expired is to:
- Log into Azure
- Go to the App registrations page
- Search for the application used by the Jira application
- Check the Certificates & Secrets column to see if the secret has expired
- If the secret is showing as Expired as illustrated in the screenshot below, then this Root Cause is relevant:
Root Cause 15 - The inbox has a large number of emails
It has been observed that the Connection Test of the Jira/JSM Mail Handlers might fail if the inbox is continuously flooded with lots of emails (such as failure delivery emails).
Root Cause 16 - There is an outbound proxy configured with Jira which is blocking outgoing requests from Jira to the mail server
If the Jira application is configured with an outbound proxy, if the proxy is not configured correctly, it might block outgoing requests sent from the Jira application to the Mail Server (Microsoft, Google...). In such case, the Jira application will fail to request an Oauth 2.0 Token which is required for the Oauth 2.0 authorization flow.
To verify if this Root Cause might be relevant, check the JVM tartup argument configured in the Jira application. If you can spot parameters like the ones listed below, then it means that the Jira application is configured with an outbound proxy, and that the outbound proxy might be preventing Jira from sending outgoing requests to the Mail Server (for example Microsoft):
-Dhttp.proxyHost=www.example.com
-Dhttp.proxyPort=8080
-Dhttps.proxyHost=172.9.x.x
-Dhttps.proxyPort=443
The values for these parameters might vary for each client environment.
Solution
Solution for Root Cause 1
Use the right scopes for Microsoft as explained in the official documentation Setting up OAuth 2.0 integration:
In case of a Microsoft Worldwide plan including Government Community Cloud (GCC), use the following scopes (this is the most common scenario):
https://outlook.office.com/IMAP.AccessAsUser.All https://outlook.office.com/POP.AccessAsUser.All offline_access
In case of a Microsoft US Government DoD or US Government GCC High plan, use the following scopes (this is the most common scenario):
https://outlook.office365.us/IMAP.AccessAsUser.All https://outlook.office365.us/POP.AccessAsUser.All offline_access
Solution for Root Cause 2
Ensure that IMAP (or POP) is enabled at the mailbox level:
- If a Microsoft Exchange mailbox is 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, enabled 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. See screenshot below for reference:
For more information, refer to the KB article Jira Service Management Mail Handler cannot be configured using Oauth 2.0 due to when IMAP (or POP) being disabled for the mail box.
Solution for Root Cause 3
Ensure that the user logging into the Microsoft portal to authorize the mailbox has 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 into 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
- Search for the mailbox, and click on the edit button (pencil icon)
- 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 cannot be configured using Oauth 2.0, due to incorrect mailbox permission.
Solution for Root Cause 4
Reach out to your Microsoft Administration team to grant the account a license allowing to access the mailbox.
One way to grant a license to the account is to go to the Azure Admin portal, as explained in Assign or remove licenses in the Azure Active Directory portal. Basically, what your admin user can do is:
- Log into https://portal.azure.com/ as an Admin user
- Go to Users and click on the account that needs a license
- After that, click on on Licenses > Assignments
For more information on how to do it, refer to the KB article Jira Mail Handler and Service Management Mail Handler cannot be configured using Oauth 2.0, due to Microsoft License issue.
Solution for Root Cause 5
To work around the bug - JSDSERVER-7058Getting issue details... STATUS , either create a folder named "Inbox", or if one already there, change the language setting of your mailbox to the original language, and then create a folder named "Inbox".
Solution for Root Cause 6
Make sure "IMAP4" is added to Client Access Rules in Office 365.
For more information on how to do it, refer to the Resolution 1 section of the KB article IMAP fails with A3 BAD User is authenticated but not connected error in Jira server integrated with Office365.
Solution for Root Cause 7
Reach out to your Firewall administrator to allow:
- traffic from the Jira Server to the internet (and to the Mail Service Provider)
- traffic on the port used by Jira to access the mailbox (the port will depend on which mail protocol is used)
Solution for Root Cause 8
If your organization allows the "multi-tenant" support account type
Go to the Azure Admin UI, and either edit the current application, so that the supported account type is set to "multitenant", or create a new application by making sure to select the type Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox):
If your organization only allows the "single-tenant" support account type
Follow the steps below:
- In the Azure Admin UI, get the tenant ID value, as explained in OAuth 2.0 and OpenID Connect protocols on the Microsoft identity platform, and as illustrated in the screenshot below:
- In Jira, go to ⚙ > System > Oauth 2.0, and change the 2 fields Authorization endpoint and Token endpoint in the Oauth 2.0 configuration page, using the following values instead (please replace <TENANT_ID> with the tenant ID):
- Authorization endpoint: https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/authorize
- Token endpoint: https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token
- After you make these 2 changes, make sure to generate a new value for the Redirect URL field, in order to save the new integration settings
- Go back to the Azure Admin UI, update the new Redirect URL value in the application in Authorization > Platform Configurations > Redirect URIs and save the changes:
Solution for Root Cause 9
If you are trying to configure a US Government DoD or GCC High account with a Jira Mail Handler (on Jira 8.10.0 or higher) or a JSM Mail Handler (on JSM 4.22.0 or higher)
Please refer to the article Guide explaining how to configure a US Government DoD or GCC High account with a Jira or a Service Management mail handler using Oauth 2.0.
If you are trying to configure a US Government DoD or GCC High account with a JSM Mail Handler on a JSM version lower than 4.22.0
Please note that such configuration is not officially supported. We highly recommend upgrading to 4.22.0 or any higher version, since this configuration supported in those version. If upgrading to 4.22.0 is not an option yet, then you might look into the 2 options below:
- Option 1
Follow the workaround provided in the feature request - JSDSERVER-6998Getting issue details... STATUS , which consists in manually updating the hosts file of the operating system to point to the US domain. However, doing this will remove the automatic failover to a new IP address in case of outages in the primary IP address:
40.66.16.130 outlook.office365.com
- Option 2
- You might consider using the paid 3rd party add-on Email This Issue (which is unsupported by Atlassian), as it allows to configure US Government Dod or GCC High accounts with Oauth 2.0
Solution for Root Cause 10
Make sure that:
- the Jira version is running on either version listed below
- 8.5.12 or any higher version on 8.5.x
- 8.13.4 or any higher version on 8.13.x
- 8.15.0 or any higher version
- the option Use two line authentication format is ticked in the configuration ⚙ > System > Incoming Mail > Mail Server, as shown in the screenshot below:
Solution for Root Cause 11
One way to ensure that the wrong MS credentials are not used by the browser while logging into MS to authorize the mailbox is to either open the Browser in incognito mode, clear the browser cache, or use a different browser.
Solution for Root Cause 12
If you are planning to configure multiple mail channels in a JSM project, make sure to use the final version of that feature by upgrading JSM to 4.22.0 or any higher version.
Solution for Root Cause 13
Make sure that the 2 following requirements are met:
- Make sure that the Load Balancer is correctly configured to ensure session stickiness as per the documentation Jira Data Center Load Balancer examples
- Make sure that only External REST API calls are redirected to that node, as per the documentation Traffic distribution with Atlassian Data Center, in the case where the Load Balancer is redirecting REST API traffic to a dedicated node
Solution for Root Cause 14
Create a new secret with a new expiration date in the application registered in Azure:
Solution for Root Cause 15
Remove the huge amount of emails from the inbox, or make the inbox empty by moving all the messages to some temp sub folder, and then re-authorize the mail server from the Jira UI. Once it the authorization process and connection test are successful, you may then move those unprocessed messages in batch to let the Jira (or JSM) mail handler process them.
Solution for Root Cause 16
Add the following startup arguments so that connections to outlook.office365.com are allowed by the outbound proxy, in case the Jira is configured with a Microsoft Mail Server:
-Dhttps.nonProxyHosts=*.office365.com
Please make sure to restart Jira for the changes to take affect.
If Jira is using a Google Mail Server, add the Google domain instead of the MS domain.