Jira Mail Handlers or Service Management Mail Handlers cannot be configured using Oauth 2.0 - The authorization or connection test fails

Still need help?

The Atlassian Community is here for you.

Ask the community

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

Examples of errors
  • When configuring a Jira Service Management Mail Handler in Project Settings > Email Requests, either of the following errors is returned:

    • Error 1:


      We couldn't connect to your mail server
      Here's the error we received: "OAuth token not defined for connection. OAuth Authorisation required."


    • Error 2

      We couldn't connect to your mail server
      JIRA couldn't open the folder 'inbox' at outlook.office365.com. Check and make sure the folder name is correct and try again.

  • When configuring a Jira mail server in ⚙ > System Incoming Mail, either of the following errors might be thrown:

    • Error 1

      Unfortunately no connection was possible. Review the errors below and rectify:
      ConnectionException: * BYE Jakarta Mail Exception: java.net.SocketTimeoutException: Read timed out

    • Error 2

      AuthenticationFailedException: AUTHENTICATE failed

    • Error 3:

      Unfortunately no connection was possible. Review the errors below and rectify: AuthenticationFailedException: Protocol error. Connection is closed. 10

    • Error 4
AuthenticationFailedException: Authentication failure: unknown user name or bad password.

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


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:

Click here to expand...

For Microsoft accounts, the scopes should match precisely the ones from the list below:

  • In case of a Worldwide plan including Government Community Cloud (GCC) which is the most common type of plan, use the following scopes:

    https://outlook.office.com/IMAP.AccessAsUser.All
    https://outlook.office.com/POP.AccessAsUser.All
    offline_access
  • In case of a US Government DoD or US Government GCC High plan, use the following scopes:

    https://outlook.office365.us/IMAP.AccessAsUser.All
    https://outlook.office365.us/POP.AccessAsUser.All
    offline_access

For GMAIL accounts, you only need to use the scope below which will work for both IMAP and POP:

https://mail.google.com/


If the scopes don't match precisely the ones mentioned above, then Root Cause 1 might be relevant.

  • The screenshot below shows an example of incorrect scope configuration:
  • The screenshot below shows an example of correct scope configuration:


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:

Click here to expand...
  • Example of fields used to run the test:
  • Example of successful test
  • Example of test failure


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.

Click here to expand...

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)

(tick)

(tick)

(tick)

(tick)

(tick)

Oauth 2.0 + IMAP Support for JSM Mail Handler (Microsoft)

(error)

(tick)

(tick)

(tick)

(tick)

Oauth 2.0 + POP Support for Jira Mail Handler + JSM Mail Handler

(error)

(error)

(tick)

(tick)

(tick)

Oauth 2.0 configuration available for any type of application other than mail servers (and configuration moved from the Oauth 2.0 page to the Application links page)

(error)

(error)

(error)

(tick)

(tick)

JSM Mail Handler hostname customization (Microsoft GCC High/DoD account support)

(error)

(error)

(error)

(tick) (4.22.0 for JSM Data Center)

(tick) (4.22.2 for JSM Server)

(tick)

Oauth 2.0 + SMTP support for Outgoing Mail

(error)

(error)

(error)

(error)

(tick)

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.

Click here to expand...

For example, let's assume that the mailbox is a Microsoft Mailbox. During the authorization process, you will be redirected to the Microsoft login page. You will need to login using the credentials from either account listed below. Failing to logging with either account will lead to the failure of the authorization or the connection test of the mailbox:

  • use the credentials of the mailbox you are using in the mail handler configuration
  • or the credentials of a service account that has the full delegated permission on the mailbox

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, or if it is a shared mailbox, then Root Cause 3 might be relevant. There are basically 2 scenarios where the authorization process might fail:

  • Scenario 1 (using the mailbox from another account):
    • The user who is logging into the Microsoft portal during the authorization process (either for the JSM Mail Handler, or the Jira Mail Server) is not the same user as the one who owns the mailbox
  • Scenario 2 (using a shared mailbox):
    • The user who is logging into the Microsoft portal during the authorization process (either for the JSM Mail Handler, or the Jira Mail Server) does not have full delegated access to the shared mailbox

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.

Click here to expand...

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 as shown below, then it is an indication that the mailbox was not granted a license (refer to the Root Cause 4 section).

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.

Click here to expand...
  • If you find the error below, then the Root Cause 1, the Root Cause 4 or the Root Cause 11, might be relevant:

    AuthenticationFailedException: AUTHENTICATE failed
  • If you find either of the 2 errors below, then the Root Causes 2 to 5 and 15 might be relevant:
    • 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 you see the following error in the Jira Logs, then the Root Causes 2, 3, 6 or 11 might be relevant

    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.


    • Additionally, if you use the MS tool Microsoft Remote Connectivity Analyzer, to test the mailbox while signing in at the authorizing user via the tool, and you see the same error "A3 BAD User is authenticated but not connected" (as shown in the screenshot below): in this case, Root Cause 11 might be the most relevant root cause
  • If you see any of the following error, then the Root Cause 7 might be relevant:

    • Example 1

      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"'


    • Example 2

      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"'


    • Example 3:

      2022-12-13 15:36:21,097+0300 http-nio-8080-exec-5 ERROR testuser XXXxXXXXXXXxX xxxxxx XXX.XX.X.XXX /rest/oauth2-client/latest/config/flow/f97d6a96-f6d3-464e-b55f-a3bd4ddca9ff [c.a.o.c.rest.resource.ClientConfigurationResource] Error occurred while authorizing an integration. The error message is: null
  • If you see any of the error below, it means that the Jira application can't access its own Base URL. It could be because the Jira server does not have access to the internet (due to some firewall configuration). In such case, the Root Cause 7 might be relevant:
    • Example 1

      2022-12-13 15:42:14,782+0300 HealthCheck:thread-7 WARN ServiceRunner     [c.a.t.healthcheck.concurrent.SupportHealthCheckProcess] Health check 'Gadget feed URL' failed with severity 'warning': 'Jira is not able to access itself through the Gadget feed URL. This is necessary so that dashboard gadgets can be generated successfully. Please verify the current Base URL and if necessary, review your network configurations to resolve the problem.'
    • Example 2

      2022-12-13 15:41:45,783+0300 HealthCheck:thread-8 ERROR ServiceRunner     [c.a.t.j.healthcheck.support.GadgetFeedUrlHealthCheck] An error occurred when performing the Gadget feed URL healthcheck
      org.apache.http.conn.HttpHostConnectException: Connect to <JIRA_BASE_URL>:443 [<JIRA_BASE_URL>/XX.XXX.XX.XX] failed: Connection refused: connect
      	at org.apache.http.impl.conn.DefaultHttpClientConnectionOperator.connect(DefaultHttpClientConnectionOperator.java:156)
      	at org.apache.http.impl.conn.PoolingHttpClientConnectionManager.connect(PoolingHttpClientConnectionManager.java:376)
      	at org.apache.http.impl.execchain.MainClientExec.establishRoute(MainClientExec.java:393)
  • If you see the following error, then the Root Cause 8 is relevant:

    2021-11-16 12:35:50,956+0100 https-jsse-nio-8443-exec-7 ERROR julien 755x4397x2 lyskqh 127.0.0.1
    /rest/oauth2-client/latest/config/flow/d4ec2ed5-fa07-4e3d-948d-0ce99fb20a40 [c.a.o.c.rest.resource.ClientConfigurationResource] Error occurred while authorizing an integration.
    The error message is:
    Error when fetching authorization response:
    {"error_description":"AADSTS50194: Application '79c86cf8-e761-4fdc-bc20-a629c5d04260'(Single Tenant - Test) is not configured as a multi-tenant application.
    Usage of the \/common endpoint is not supported for such applications created after '10\/15\/2018'.
    Use a tenant-specific endpoint or configure the application to be multi-tenant.\r\nTrace ID: d7599cf0-813f-4495-8317-577479857f00\r\nCorrelation ID: 34687097-cd9a-4300-9639-b561f5effd26\r\nTimestamp: 2021-11-16 11:35:47Z",
    "error":"invalid_request"}
  • If you see the following error, then the Root Cause 9 is relevant:

    2022-03-14 04:54:05,515-0500 https-openssl-nio-443-exec-10 ERROR julien 294x1151x3 ntpr0w 10.208.130.153 /rest/oauth2-client/latest/config/flow/ee857406-fc2a-4827-a993-48dfae72bdf4 [c.a.o.c.rest.resource.ClientConfigurationResource] Error occurred while authorizing an integration. The error message is: AADSTS900432: Confidential Client is not supported in Cross Cloud request.
    Trace ID: 607ad2c0-6224-4192-aa84-21adef8b1700
    Correlation ID: 5ee0f822-fa46-4c66-a745-ea2f65339cca
    Timestamp: 2022-03-14 09:54:02Z
  • If you see the following error, then the Root Cause 10 is relevant:

    Unfortunately no connection was possible. Review the errors below and rectify: AuthenticationFailedException: Protocol error. Connection is closed. 10
  • If Jira is configured with a cluster of nodes running behind a load balancer, and if you see any of the following error in the logs, then the Root Cause 13 might be relevant:
    • Error 1

      Failed to retrieve the OAuth token. Try authorizing again or contact your Jira system admin. Details:
      Token already marked as invalid
    • Error 2

      Exception when MailPullerWorker pulls emails: 
      com.atlassian.jira.internal.mail.processor.errors.MailConnectionException: OAuth token not found with ID XXXXXXXXXXXXXXXX.
  • If you see the following error, then Root Cause 14 might be relevant:

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

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.

Example of HAR file analysis
  • The request below is correctly redirected to the Node that the user was already on (Node 1):
  • The request below is incorrectly redirected to a different Node (Node 3) that the user was already on, while it should have been redirected to the same node (Node 1):


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-7058 - Getting 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).

(warning) 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-6998 - Getting 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-72033 - Getting 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
  • (warning) 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

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

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-7058 - Getting 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:

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-6998 - Getting 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:

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

(warning) Please make sure to restart Jira for the changes to take affect.

(warning) If Jira is using a Google Mail Server, add the Google domain instead of the MS domain.


Last modified on Oct 12, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.