Summary

Both types of mail handlers (Jira and Service Management) can't be configured with a Microsoft Mailbox (shared or non shared) using the Oauth 2.0 authentication:

• Configuring a Jira Service Management (JSM) Mail Handler for a Service Management project via the page Project Settings > Email Request fails while using the authorize button  with the Oauth 2.0 authentication
• Configuring a Jira Mail Server in ⚙ > System > Incoming Mail fails during the Test Connection step

Environment

Jira Service Management 4.10.0 / Jira 8.10.0 and higher, integrated with Office 365 or Microsoft Exchange

Diagnosis

• An Oauth 2.0 integration was configured in ⚙ > System > Oauth 2.0, with the same scopes as the ones mentioned in Integrating with Oauth 2.0, and the connection test was successful
• When trying to configure a JSM Mail Handler via the page Project Settings > Email Request,

  • the following error is thrown in the UI

    Here's the error we received: "OAuth token not defined for connection. OAuth Authorisation required."

    

  • the following error is thrown in the Jira Incoming Mail Logs

    2021-11-22 12:22:32,914+0100 ERROR [] https-jsse-nio-8443-exec-5 julien 742x19484x1 1nxdphq 127.0.0.1 /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:76) [?:?]
    	at com.atlassian.jira.internal.mail.processor.feature.channel.connectionverifier.DefaultChannelConnectionVerifier.verifyConnectionDefinition(DefaultChannelConnectionVerifier.java:58) [?:?]
    	at jdk.internal.reflect.GeneratedMethodAccessor3792.invoke(Unknown Source) [?:?]
    	at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) [?:?]
    	at java.base/java.lang.reflect.Method.invoke(Method.java:566) [?:?]

  • the following error may be thrown in the Jira application logs

    2022-04-12 11:15:27,997+0100 http-nio-8080-exec-52 ERROR admin 675x11838312x2 12abcde 10.12.30.40,10.20.30.40 /rest/servicedesk/1/servicedesk/ABC/incomingemail/oauth/validateandsaveflow/01a2bc34-56d7-8efg-9h0i-1234jk5lmnop [c.a.s.i.rest.emailchannel.EmailChannelResource] Failed to validate and save token: jep.mail.connection.verifier.unknown.error : 'Here's the error we received: "Authentication failure: unknown user name or bad password."'

• When trying to configure a Jira Mail Server in ⚙ > System > Incoming Mails 
  • Clicking on the Authorize button leads to a successful result
    

  • Clicking on the Test Connection button leads to an error thrown in the UI

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

    

  • The following error is thrown in the Jira logs

    2021-11-22 12:23:25,355+0100 https-jsse-nio-8443-exec-9 ERROR julien 743x19539x1 1nxdphq 127.0.0.1 /secure/admin/VerifyPopServerConnection!add.jspa [c.a.j.p.mail.webwork.VerifyMailServer] Unable to connect to the server at outlook.office365.com due to the following exception: com.sun.mail.iap.ConnectionException: * BYE Jakarta Mail Exception: java.net.SocketTimeoutException: Read timed out

• The mailbox is either an account mailbox (scenario 1), or a shared mailbox (scenario 2):
  • Scenario 1 (account 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) is not the same user as the one who owns the mailbox, and does not have full access on that mailbox
    • For example, the user "julien@microsoft.com" is trying to configure a mail handler/server to pull emails from the mailbox "bruno@microsoft.com". In other words:
      • An Oauth 2.0 integration is configured in Jira in ⚙ > System > Oauth 2.0, using an application configured in Azure under "julien@microsoft.com" account
      • The mailbox "bruno@microsoft.com" is used in the email address field of the JSM Mail Handler or the Username field of the Jira Mail Server
      • When clicking on the authorization button, the Jira user is redirected to Microsoft Login page, and the user logs in as "julien@microsoft.com" instead of "bruno@microsoft.com"
        
  • Scenario 2 (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 access to the shared mailbox.
    • One way to confirm that this user does not have full access to the shared mailbox when using Office 365 is to go to the URL below (after replacing sharedmailbox_email_address with the email address of the shared mailbox), login as the user, and check if this this user is able to see the content of this mailbox. If the error "something went wrong" is thrown in the UI instead (as shown below), then it means that the user does not have full access on the shared mailbox:
      https://outlook.office.com/mail/sharedmailbox_email_address/inbox
      

Cause

Such configuration will only work if the user authorizing the mail handler configuration over Oauth 2.0 in JSM/Jira is granted delegated permissions (Full Access) on:

• the account mailbox (scenario 1)
• the shared mailbox (scenario 2)

If such permission is not granted on the mailbox, then the authorization process will fail.

Solution

Ensure that the user authorizing the mail handler configuration over Oauth 2.0 in JSM/Jira is granted delegated permissions (Full Access) on the mailbox (account mailbox or shared mailbox).

Taking the example from the scenario 1 mentioned above, we basically need to ensure that the user "julien@microsoft.com" is granted the delegated permission on "bruno@microsoft.com" mailbox.

In Office 365, this can be done as shown below. For more information, please refer to 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 (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