要約

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):

AuthenticationFailedException: Authentication failure: unknown user name or bad password.

Authorization has failed. Go to Jira administration > System > Oauth 2.o and verify the integration you've selected for this mail server

ConnectException: Connection refused

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 listed below:

• a Jira Service Management (JSM) Mail Handler from the page Project Settings > Email Requests
• a Jira Mail Handler from the page ⚙ > System > Incoming Mail

環境

Jira Service Management 4.10.0 / Jira 8.10.0 and higher

診断

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:

https://mail.google.com/

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.

• This tool is not available for GCC High environments.

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.

UTC Date: 2021-12-08T09:50:21.069Z
BootResult: configuration
Client Id: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Session Id: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX
Client Version: 20211129004.15
err: Microsoft.Exchange.Clients.Owa2.Server.Core.OwaUserHasNoMailboxAndNoLicenseAssignedException
esrc: StartupData
et: ServerError
estack: Error: 500
    at i (https://outlook.office.com/mail/inbox/:363:209906)
    at https://outlook.office.com/mail/inbox/:363:147412
st: 500
ehk: X-OWA-Error
efe: CY4PR16CA0042, AS8P250CA0011
ebe: CY4PR10MB1639
emsg: UserHasNoMailboxAndNoLicenseAssignedError

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.

2025-01-03 06:31:00,013-0100 WARN [JIRA MAIL SERVER] Caesium-1-2 anonymous    Random mail subject [10300]: com.sun.mail.util.MailConnectException: Couldn't connect to host, port: imap.gmail.com, 993; timeout 10000 while connecting to host "imap.gmail.com" as user "xxxxx" via protocol "SECURE_IMAP", caused by: java.net.ConnectException: Connection refused

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.

原因

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-7058 - Attempting to configure a mailbox with no 'inbox' folder fails with message "OAuth token not defined for connection. OAuth Authorisation required".

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 support for GCC accounts have been added as outlined in JSDSERVER-6998 - Office 365 using OAuth 2.0 doesn't support GCC customers

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-72033 - Microsoft POP Support for Emails using OAuth 2.0

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 startup 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.

ソリューション

根本原因の解決策 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

根本原因の解決策 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.

根本原因の解決策 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.

根本原因の解決策 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.

根本原因の解決策 5

To work around the bug JSDSERVER-7058 - Attempting to configure a mailbox with no 'inbox' folder fails with message "OAuth token not defined for connection. OAuth Authorisation required", 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". 

根本原因の解決策 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.

根本原因の解決策 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)

根本原因の解決策 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

以下のステップを実行します。

• 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:
  

根本原因の解決策 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:

• オプション 1

  • Follow the workaround provided in the feature request 

    • JSDSERVER-6998 - Office 365 using OAuth 2.0 doesn't support GCC customers, 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

• オプション 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

根本原因の解決策 10

以下を確認してください。

• 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:
  

根本原因の解決策 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.

根本原因の解決策 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.

根本原因の解決策 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

根本原因の解決策 14

Create a new secret with a new expiration date in the application registered in Azure:

根本原因の解決策 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.

根本原因の解決策 16

オプション 1

Configure Jira to connect to the mail server through the outbound proxy by adding the following startup arguments:

mail.<protocol>.proxy.host
mail.<protocol>.proxy.port  

For instance, to configure the proxy proxy.example.org on port 993 for the IMAPS protocol (please replace the host and port with your actual values), you would add the following JVM properties:

-Dmail.imaps.proxy.host=proxy.example.org -Dmail.imaps.proxy.port=993

For further details on these parameters, please refer to the article How to configure outbound proxy for mailing in Jira.

オプション 2

Configure Jira to connect to the mail server directly and not through the outbound proxy by adding the mail server in the http.nonProxyHosts startup argument (in addition to the mandatory localhost and Jira base URL, as suggested in the documentation here):

-Dhttp.nonProxyHosts=localhost|jira.mycompany.com|mailserver.com

You can also use a wildcard character (*) for matching the whole mail server's domain.

For example, if Jira is configured with a Microsoft Mail Server (outlook.office365.com), you can add the following startup argument: 

-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.