Summary

Integrating Jira's mail handler with an external mail server using OAuth 2.0 can be complex. Here are common issues and solutions. You might face issues due to misconfigurations in Jira, the mail server, or the network.

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 two types of Mail Handlers listed below:

• a Jira Service Management (JSM) Mail Handler from the Email Requests section in Project Settings

• a Jira Mail Handler from the Incoming Mail section under ⚙ > System

Environment

Jira Service Management 4.10.0 / Jira 8.10.0 and higher

Solution

The error messages don't directly indicate a specific root cause. Please use the following steps for the easiest troubleshooting approach

Checking the scopes

Check out Resolve OAuth 2.0 Scope Issues for Jira Mail Handlers in Data Center for the correct scopes and steps

Check account permissions and mail protocol (IMAP/POP)

With the Microsoft Remote Connectivity Analyzer, you can find out if the IMAP protocol is enabled as well as if the mailbox user has the permissions needed for the integration.
Follow Fixing IMAP and User error with OAuth 2.0 and Jira Data Center .

Ensure that the account used for the mailbox is either the owner or has full permissions on the mailbox using Jira Mail Handler and Service Management Mail Handler cannot be configured using Oauth 2.0, due to incorrect mailbox permission

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 types of Microsoft Accounts (Microsoft Worldwide/GCC accounts, US Government DoD, US Government GCC High accounts...).

Type of functionality	8.10.0 / 4.10.0	8.12.0 / 4.12.0	8.15.0 / 4.15.0	8.22.0 / 4.22.0	9.2.0 / 5.2.0
OAuth 2.0 support for Incoming Mail: IMAP + OAuth 2.0 Support for Jira Mail Handler (Microsoft + Google) IMAP + OAuth 2.0 Support for JSM Mail Handler (Google only)
OAuth 2.0 + IMAP Support for JSM Mail Handler (Microsoft)
OAuth 2.0 + POP Support for Jira Mail Handler + JSM Mail Handler
You can configure OAuth 2.0 for applications other than mail servers. Find this under Application links instead of OAuth 2.0.
JSM Mail Handler hostname customization (Microsoft GCC High/DoD account support)				(4.22.0 for JSM Data Center)   (4.22.2 for JSM Server)
OAuth 2.0 + SMTP support for Outgoing Mail

• If you are using the POP protocol with an unsupported version of Jira the error Protocol error. Connection is closed. 10 will be thrown.

• The error AADSTS900432: Confidential Client is not supported in Cross Cloud request. points to a Microsoft US Government DoD or US Government GCC High account. Check that your Jira version is supported and verify the used scope

Verifying that the mailbox has been 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.

One way to verify if the mailbox is granted a license is to log directly into the mailbox in Microsoft Outlook (https://outlook.office.com/mail/inbox), using the same credentials as the account used in the authorization process. If the error "UserHasNoMailboxAndNoLicenseAssignedError" is thrown in the UI, then it is an indication that the mailbox was not granted a license.

For more information about this root cause, please refer to the KB article Resolving Jira Mail Handler Configuration error due to Microsoft license

Check for user credential caching

We have seen that, in some rare cases, incorrect MS user credentials are cached in the browser.

One way to ensure that the browser does not use the wrong MS credentials 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.

Check your Microsoft Mailbox language setting

If your default language is not set to English, you might be impacted by the Jira Service Management bug. See our 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". This has been fixed in JSM Version 5.4.2 / 5.6.0 and later

Checking the Jira application logs

Once you've checked the points listed above, the next step is to check the Jira logs (in either the file atlassian-jira.log or atlassian-jira-incoming-mail.log).

Authenticate Failed

AuthenticationFailedException: AUTHENTICATE failed

The following articles would be relevant:

• Resolve OAuth 2.0 Scope Issues for Jira Mail Handlers in Data Center

• Resolving Jira Mail Handler Configuration error due to Microsoft license

'OAuth token not defined for connection', or ‘could not open Inbox’

• Example of error 1:

  2021-11-10 14:51:00,802+0000 ERROR [] http-nio-8080-exec-12 testuser XXXxXXXXXXXxX xxxxxx XXX.XX.X.XXX/rest/servicedesk/1/servicedesk/admin/email/test Unable to connect to the server at outlook.office365.com due to the following exception:
  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.channel.connectionverifier.DefaultChannelConnectionVerifier.verifyConnectionDefinition(DefaultChannelConnectionVerifier.java:87) [?:?]
  at com.atlassian.jira.internal.mail.processor.feature.channel.connectionverifier.DefaultChannelConnectionVerifier.verifyConnectionDefinition(DefaultChannelConnectionVerifier.java:69) [?:?]
  at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) [?:1.8.0_292]
  at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62) [?:1.8.0_292]
  at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) [?:1.8.0_292]
  at java.lang.reflect.Method.invoke(Method.java:498) [?:1.8.0_292]

• Example of error 2:

  2021-11-10 14:50:57,000+0000 http-nio-8080-exec-16 ERROR testuser XXXxXXXXXXXxX xxxxxx XXX.XX.X.XXX
  /rest/servicedesk/1/servicedesk/VYRGLOGTB/incomingemail/oauth/validateandsaveflow/f6c632f6-82c3-43d8-a821-447e47a32948 [c.a.s.i.rest.emailchannel.EmailChannelResource]
  Failed to validate and save token: jep.mail.connection.verifier.missing.folder.error :
  'JIRA couldn't open the folder 'inbox' at outlook.office365.com. Check and make sure the folder name is correct and try again.'

If this has not been fixed by any of the above, check if the inbox is continuously flooded with lots of emails (such as delivery failure emails). Remove the huge amount of emails from the inbox, or make the inbox empty by moving all the messages to some temp subfolder, and then re-authorize the mail server from the Jira UI. Once 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.

'A3 BAD User is authenticated but not connected'

2014-09-12 07:40:48,051 ERROR [365 IMAP] QuartzScheduler_Worker-3 ServiceRunner    Help Desk Handler[10100]: Messaging Exception in service 'com.atlassian.jira.service.services.mail.MailFetcherService$MessageProviderImpl' when getting mail: A3 BAD User is authenticated but not connected.
javax.mail.MessagingException: A3 BAD User is authenticated but not connected.;
  nested exception is:
    com.sun.mail.iap.BadCommandException: A3 BAD User is authenticated but not connected.
    at com.sun.mail.imap.IMAPFolder.open(IMAPFolder.java:961)
    at com.atlassian.jira.service.services.mail.MailFetcherService$MessageProviderImpl.getAndProcessMail(MailFetcherService.java:254)
    at com.atlassian.jira.service.services.mail.MailFetcherService.runImpl(MailFetcherService.java:401)
    at com.atlassian.jira.service.services.file.AbstractMessageHandlingService.run(AbstractMessageHandlingService.java:257)
    at com.atlassian.jira.service.JiraServiceContainerImpl.run(JiraServiceContainerImpl.java:61)
    at com.atlassian.jira.service.ServiceRunner.execute(ServiceRunner.java:48)
    at org.quartz.core.JobRunShell.run(JobRunShell.java:195)
    at org.quartz.simpl.SimpleThreadPool$WorkerThread.run(SimpleThreadPool.java:520)
Caused by: com.sun.mail.iap.BadCommandException: A3 BAD User is authenticated but not connected.

If that has not been fixed by any of the above check out IMAP fails with A3 BAD User is authenticated but not connected error in Jira server integrated with Office365.

'Connection reset by peer: socket write error' and other connection errors

Any connection-related errors like for example:

2021-07-22 08:26:11,660+0200 ajp-nio-0.0.0.0-8029-exec-16 ERROR testuser XXXxXXXXXXXxX xxxxxx XXX.XX.X.XXX
/rest/servicedesk/1/servicedesk/PFTS/incomingemail/oauth/validateandsaveflow/bf54cc45-4651-4d72-ab63-796d519fc236 [c.a.s.i.rest.emailchannel.EmailChannelResource]
Failed to validate and save token: jep.mail.connection.verifier.unknown.error :
'The following error occurred: "Connection reset by peer: socket write error"'

2021-07-22 08:26:11,660+0200 ajp-nio-0.0.0.0-8029-exec-16 ERROR testuser XXXxXXXXXXXxX xxxxxx XXX.XX.X.XXX
/rest/servicedesk/1/servicedesk/PFTS/incomingemail/oauth/validateandsaveflow/bf54cc45-4651-4d72-ab63-796d519fc236 [c.a.s.i.rest.emailchannel.EmailChannelResource]
Failed to validate and save token: jep.mail.connection.verifier.unknown.error :
'The following error occurred: "connect timed out"'

2022-01-08 09:11:54,025-0500 ERROR [] Caesium-1-2 anonymous     Messaging Error when MailPullerWorker pulls emails from XXXXXXXX: * BYE Jakarta Mail Exception: java.net.SocketTimeoutException: Read timed out
javax.mail.MessagingException: * BYE Jakarta Mail Exception: java.net.SocketTimeoutException: Read timed out;
      nested exception is:
        com.sun.mail.iap.ConnectionException: * BYE Jakarta Mail Exception: java.net.SocketTimeoutException: Read timed out
    at com.sun.mail.imap.IMAPStore.protocolConnect(IMAPStore.java:714) [jakarta.mail-1.6.5-atlassian-2.jar:1.6.5-atlassian-2]
    at javax.mail.Service.connect(Service.java:342) [jakarta.mail-1.6.5-atlassian-2.jar:1.6.5-atlassian-2]
    at javax.mail.Service.connect(Service.java:222) [jakarta.mail-1.6.5-atlassian-2.jar:1.6.5-atlassian-2]
    at javax.mail.Service.connect(Service.java:243) [jakarta.mail-1.6.5-atlassian-2.jar:1.6.5-atlassian-2]
    at com.atlassian.jira.internal.mail.processor.feature.puller.MailPullerWorker.pullEmailForConnection(MailPullerWorker.java:174) [jira-email-processor-plugin-5.12.12-REL-0002.jar:?]

could indicate that a firewall is blocking traffic from Jira to the internet, or to specific ports (for example, 993 for IMAPS).

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.

There is an outbound proxy configured with Jira, which is blocking outgoing requests from Jira to the mail server

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

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, etc.). In such a case, the Jira application will fail to request an OAuth 2.0 Token, which is required for the OAuth 2.0 authorization flow. Refer to  How to configure outbound proxy for mailing in Jira for how to set this up correctly.

The application was created in Azure with the "single-tenant" account type

Any error regarding

Application '<idstring>'(<applicationname) is not configured as a multi-tenant application.

In our Detailed steps to configure OAuth 2.0 integration with Microsoft Azure, we recommend that the application's support account type be set to Accounts in any organizational directory (Any Azure AD directory—Multitenant) and personal Microsoft accounts (e.g., Skype, Xbox).

Confirm that you use the “Multitenant” type when creating the application in Azure. If your organization only allows the "single-tenant" support account type use Setup the "single-tenant" account type Azure mail with Jira Data Center

The client secret of the Azure application has expired

OAuth token is unrecoverable - manual re-authorisation required
com.atlassian.oauth2.client.api.storage.token.exception.UnrecoverableTokenException: Token already marked as invalid

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.

You will need to create a new secret in Azure and update the configuration accordingly.

Jira is running on a cluster of nodes, and session stickiness is not respected

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.

Make sure that the two following two 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