Integrate with Microsoft 365 using OAuth

Owned by Andy Brook [Plugin People]
Last updated: Apr 05, 2023 by Ryan Clifton
6 min read

JEMHC can be configured to communicate with your Microsoft 365 mail accounts in order to send notifications or receive email for processing.

Prerequisite setup in Azure Portal

As an Azure admin, ensure that users of JEMHC can request permissions via Microsoft Azure > Enterprise Applications > User settings. You will also need identify Users/Groups/Roles who will authorise admin consent requests from users configuring JEMHC.

Registration of JEMHC in your domain

Automatic registration through JEMHC authentication

Registration is automatic when a domain admin account is used in JEMHC incoming/outgoing mail connections through the “Sign in with Microsoft Button”:

On successful authentication, the JEMHC app registration will be made, here you can see 08b9fc2c-f6b8-4da0-8d4d-c065edfa949b is the ID of the application

 

It is now possible to delete the Message Source / Message Outbound in JEMHC using the Domain Admin account, and supply instead the mailbox user account, using the ‘play’ icon to validate the connection:

Manual registration before JEMHC authentication

We have had a length support call with Microsoft. No, you cannot register JEMHC in another other way than the above. JEMHC is not a user facing app, so is not in the ‘app gallery’ (costs with this are significant).

Is your Jira admin account single sign on with O365 as well? Having problems signing in to the mailbox?

It's solvable but not easy, see:

Granting consent

In order for JEMHC to access your mail accounts, it needs specific permissions. These permissions are delegated type permissions, meaning that JEMHC is delegated with the permission to act as a signed-in user when it interacts with mail accounts.

Consent needs to be given for JEMHC to use these permissions. Consent can be granted either by a single user (user consent) or for all users by an administrator (admin consent).

User consent

Usually you will want to grant consent on a per-account basis. Below is an example of a user consent screen that will be shown when creating a Microsoft 365 message source for JEMHC. The checkbox is only seen when when signed into an admin account, and changes the consent to an organization-wide admin consent.

Note that legacy EWS type connections don’t work with user consent. These connections must use admin consent. The default and recommended Graph type connections work with both consent by individual users and admins.

Admin consent

Once the JEMHC application is listed in Azure Portal as an Enterprise Application, you can choose to consent for all accounts in your organization. This means the above user consent screen will not be shown when connecting JEMHC to Microsoft 365. This can be done via Azure Portal > Enterprise applications > Enterprise Mail Handler for Jira Cloud (JEMHC) > Permissions.

Creating a connection

The following can be done via the Message Sources or Message Outbounds page under the Messaging tab, depending on whether you want to process or send emails respectively.

  1. From the top right of the screen, select Sign in with Microsoft

  2. At this point, you may be asked to grant consent to JEMHC acting on behalf of the signed in user. See the previous section on granting consent for more information.

  3. After granting consent to the request, a screen confirming successful authorization is shown:

  4. Returning to JEMHC, you should now see the new connection:

     

  5. Clicking the green ping icon will then test the connection. A successful test will look similar to this:

     

  6.  The mail connection is now ready for use. These steps are identical for setting up both Message Sources and Message Outbounds.

Connection types

There are currently 2 types of connection JEMHC can make with Microsoft 365. Graph API connections make use of the Microsoft Graph API in order to access resources. These are recommended, and the default when the “Sign in with Microsoft” button is used inside the JEMHC UI.

Before addition of Graph API connections, EWS API connections were used. This connection type can still be created via the “create” button in the JEMHC UI, but will be removed at a later date.

Common Problems

Our support doesn’t extent to 3rd party mailhost configuration, we regret we are unable to help with detailed analysis, the following is mean to offer some insight and push you in the right direction for a resolution:

The provided grant has expired due to it being revoked, a fresh auth token is needed

You may be notified of a Message Source being offline:

SimpleHttpClientException: EWS. invalid_grant - AADSTS50173: The provided grant has expired due to it being revoked, a fresh auth token is needed. The user might have changed or reset their password. The grant was issued on '2022-07-19T15:24:40.8668421Z' and the TokensValidFrom date (before which tokens are not valid) for this user is '2023-03-13T20:21:32.0000000Z'…

This typically means that the Authentication of the inbound Source has not been used for period of time, and has been revoked by the mailhost. A re-authentication step is required in the Incoming Mail Source to get a auth token.

Device object was not found in the tenant

SimpleHttpClientException: EWS. invalid_grant - AADSTS700003: Device object was not found in the tenant ….

The offered solution seems to be:

The reason that the tokens are rejected is because the presence of the deviceId claim indicates a binding to that device and when this device is not found in the directory it indicates a revocation action where the device was deleted or disabled and tokens for that device will no longer be valid.

HttpErrorException: The remote server returned an error: (401)

Typically this means that the mailserver is disallowing the use of the mailbox. As observed https://stackoverflow.com/questions/45725630/ews-connection-to-office365-fails-401-unauthorized it may be the case you need to request through your mailhost admin that the related mailbox to be specifically accessible for this app

Harmless problems

Some problems are transitory, there is nothing to typically do in these cases as connections are retried, examples of problems that can typically be ignored are:

  • SocketTimeoutException: Read timed out

 

Related articles

Filter by label

There are no items with the selected labels at this time.